0. Objective

This document aims to cover all aspects of GovStack Specification lifecycle, including the operating procedures for the Working Groups that create specifications. It’s objective is to ensure there are clear processes for the different participants and stakeholders using, building and implementing the GovStack framework.

Underlying this process is agreement to the GovStack Model of Interoperability described in https://govstack.gitbook.io/specification/architecture-and-nonfunctional-requirements/introduction.

1. Introduction

The GovStack initiative aims to build a common understanding and technical practice on fundamental reusable and interoperable digital components, which we collectively refer to as Building Blocks. Our effort is expert-driven and community-based, and includes the participation of multiple stakeholders to bring together expertise for strengthening a government's cross-agency architecture view. You can view a more extensive explanation about GovStack’s approach on the https://govstack.gitbook.io/specification/architecture-and-nonfunctional-requirements book.

The GovStack initiative does this by developing Specifications through its Working Groups, and its Specifications Track Process, which is strategically supported by GovStack's Governance bodies. Specifications are developed through working groups by consensus, soliciting reviews, both internal and from the public, and incorporating implementation feedback from Governments or Software solutions adopting the specifications.

2. Obsoletes

This document is meant to update the following documents:

• Specification Development Roles and Processes

• Scope and Overall Principles

• Roles

• GovStack Quality Criteria

• Publication cycles

• Govstack Building Block Cookbook

3. References

3.1.1 Internal

• https://govstack-global.atlassian.net/wiki/spaces/~615604c2bfa2c1006b775001/embed/1031438441?atl_f=PAGETREE

• https://govstack-global.atlassian.net/wiki/spaces/~615604c2bfa2c1006b775001/embed/1017511950?atl_f=PAGETREE

• https://docs.google.com/document/d/1WeZpPKPnSkpiG8u-dyMG77bB7qJqp3iJm7cme8dHTLc/edit?tab=t.0#heading=h.lg23kcbmrlgn

• Adaptor Concept

• Building Block Working Groups

• Charter (Governance Committee)

• Organisational Structure

• https://govstack-global.atlassian.net/wiki/spaces/GH/pages/215023641

• https://govstack-global.atlassian.net/wiki/spaces/GH/pages/100958232

• https://govstack-global.atlassian.net/wiki/spaces/GH/pages/54788097

• https://govstack-global.atlassian.net/wiki/spaces/GH/pages/89358337

3.1.2 External

• https://www.w3.org/policies/process/

• https://www.w3.org/guide/standards-track/

• https://adr.github.io/

• https://en.wikipedia.org/wiki/Architectural_decision

• https://govstack-global.atlassian.net/wiki/spaces/~615604c2bfa2c1006b775001/pages/1022918670

4. Working Groups

4.1 What is a Working Group?

A Working Group (WG) is an community through which experts on an area of expertise and with an interest on governmental interoperability, convene around how to implement the GovStack model on such topic.

4.2 Scope

A Working Group provides an ongoing space for topic stakeholders to:

1. Create specifications regarding their area of expertise

2. Share real-world experiences and feedback regarding the implementation of existing specifications

3. Advance minor and major changes to existing specifications

4. Promote publicly the usage of the specifications under the trust of their working group, the promotion of real-life use cases of the specifications, and any outreach activities regarding their work

5. Identify potential software solutions that could comply with the specifications and assess the compliance of said solutions

Even though Working Groups are on-going, they operate under the logic of annual charters that must be renewed, so a Working Group is expected to remain active and under the same goals and facilitator teams for the running year.

4.3 Composition

A Working Group is composed by the following roles:

• Members: Anyone that joins the Working Group either in a casual or more permanent fashion. Members can contribute with either their expertise, feedback, or presence through attending the Working Group events, or participating in any asynchronous activities or discussions in the Working Groups participation channels.

• Representative: One or two people per working group who agree to the responsibility of representing the Working Group interests within the wider GovStack governance. Representatives will be the main Points of Contact for a Working Group and their responsibilities as follow:

  • Coordinate and report progress on the annual goals of a charter.

  • Represent their group in the Architecture Working Group (especially if they belong to Foundational Building Blocks) to decide and be consulted on cross-functional requirements.

  • Coordinate the activities for the creation of a new specification, or the proposal and facilitation of a new version, major or minor, of an existing specification and report its progress to the Technical Facilitation Team, as detailed in section https://govstack-global.atlassian.net/wiki/spaces/GH/pages/1036124166/GovStack+Meta+Specification#5.3-The-Specification-Track-Process of this document

  • Coordinate the work needed for any request to obsolete an existing specification.

• Facilitators: The team tasked with the responsibility of organizing all of the Working Group activities. Having a group of facilitators allows for the WG representative to not shoulder all of the responsibilities and workload of organizing a working group, and offers an outlet space for members that want to get involved further in their WG operations. A WG Facilitator is expected to remain active within the working group for the period

4.4 Minimum tools and responsibilities

The following are responsibilities and tools available to the WG facilitation team:

• The creation of the Annual Charter: A WG will work together along with its members to propose a document that specifies the goals and scope of the working group for the year. This SHOULD include any activities they may consider. A Charter may be updated in the middle of the running year to include new objectives or update or delete existing ones according to their needs, however the document will need to be up-to-date, changes should be documented and communicated and the document should be available publicly.

• The maintenance and upkeep of the Working Group community calendar: A calendar will be provided where all activities for the Working Group are to be recorded. The calendar will help the Working Group and the GovStack technical facilitation team to communicate the activities of the Group for outreach. It will also become the common place where all members of the community can subscribe so that they can always be informed about the activities of their group.

• The documentation of the Working Group activities on their confluence webpage and the up-to-date keeping of the WG public page

• Access, administration and up-keeping of the Working Group’s communal spaces and channels: The working group facilitators will have access to several spaces that serve as the WG’s infrastructure to perform its activities. The minimum set of tools and their maintenance is as follows:

  • Slack Channel

  • Confluence webpage

  • Public Webpage

  • A member mailing list

• Some other tools are available upon request, but not limited to:

  • An online meeting platform

  • Access to the Sandbox to test the compliance of new or existing solutions

  • Access to GovStack’s swagger to create and document OpenAPI specifications

• When in the process to write a new specification or advance an existing one to another version:

  • Access to the Gitbook

  • Access to Jira ticketing system

  • Access to GovStack’s GitHub

• Help and assistance: As part of the GovStack wider community, a Working Group has the right to request different types of assistance to fulfill their goals. Including but not limited to:

  • The assistance of the technical facilitation team to review any work they have, answer any questions or escalate any matter to other GovStack teams through either the TC Facilitation team office hours or directly.

  • Assistance on the promotion of the WG activities and milestones through the use of GovStack’s communication channels and its relation to global and regional DPG and DPI networks.

  • Technical mentors: People outside their area of expertise that may provide support hours to solve a delimited problem. WG facilitators may request this assistance through the Technical Facilitation team.

  • Support from the GovStack institution to apply to any funding or to raise or receive donations to complete specific projects that advance the WG goals.

• Budgeting (Experimental): The Working Group will have access to budget to complete their activities and to use it as they see fit. To request a budget the following needs to be made:

  • Project scope: All budget request should be related to activities denoted on the Annual Charter

  • Budget allocation: A detail of where the budget wants to be allocated. Examples include: Hours to hire a Lead, money to complete a compliance evaluation, event organizing expenses, etc.

  • A minute signed by members of the WG where a session was held and decisions where made about the budget request.

4.4.1 Spaces available to Working Groups

The following are designated spaces to which Working Group members have access

• Slack, for immediate communication

• Confluence, for working documents

• Jira, for the tracking of tasks

• GitBook, for publishing and change management of specifications

4.5 Working Group Creation and the creation of the Annual Charter

4.5.1 Creation of a Working Group

The creation of a Working Group starts with the creation of a Charter, which is a document that outlines the Working Group scope, objectives, facilitators, meeting frequencies, communication channels and other relevant information.

The charter is to be renewed annually, which allows the Working Group to set annual goals and distribute their time commitments accordingly.

A charter and its objectives MAY be changed upon documented agreement via a meeting minute.

Once the charter is written and agreed to, the Working Group facilitators, via the Working Group Leads, SHOULD submit the Charter to the Technical Facilitation Team for creation and approval.

4.5.2 Creation and renewal of a Charter

A Working Group Charter MUST contain all of the following information:

• The group’s mission

• The scope of the group’s work

• A list of Facilitators that will be running the group and their expected time commitment and level of involvement by the Team (e.g., to track developments, write and edit technical reports, develop code, or organize pilot experiments).

• Expected milestones

• Meeting mechanisms and expected frequency

• Communication mechanisms to be employed within the group, between the group and the rest of the GovStack community and with the general public

• An estimate of the expected time commitment from participants.

• The designation of 1 or 2 Working Group Leads that will remain as the Points of Contact for the Working Group.

If the Working Group wants to advance existing specifications or create new ones during the year, the following information MUST be included:

• Description of the advancement to specifications to be achieved

• Motivations to advance the needed specifications

• Expected milestones to be achieved

• Responsible Point of Contact

• A list of members that committed to work on the specification

In the case of existing Working Groups, a Charter document SHOULD be built in an open way, so that participants are able to contribute to the document.

Once submitted, a Charter document MUST be published by the Technical Facilitation team on {Resource} to remain open to the GovStack community for comments for at least 2 weeks.

The Technical Facilitation team SHALL use GovStack’s public communication channels to announce a request for comments to the Charter.

Once comments are receive, both the Technical Facilitation Team and the Working Group Facilitation team have between a day and up to 2 weeks to resolve all comments and publish a resolution to launch or decline the creation of the working group.

4.5.3 Dissolution of a Working Group

A Working Group can be dissolved upon the following three scenarios:

• When members of the Working Group decide upon an assembly documented through a meeting minute to dissolve the group, and given that the meeting was announced with at least 2 weeks anticipation through the Working Group’s communication channels.

• When the Advisory Board decides upon a public assembly and publishes its reasons through a meeting minute.

• When a Working Group becomes inactive 6 months after the expiration of their last annual charter. In this case, dissolution of a Working Group MUST be documented by the Technical Facilitation Team, which MUST evaluate beforehand if the Working Group can be re-activated through an open call.

4.5.4 Becoming a member and membership finalization

• Who is a participant

  • The Code of Conduct

  • The Contributor Code

  • Participating as an Individual

  • Participating on behalf of an organization

• Process for becoming a lead

  • Election and resignation process

• Process for becoming part of the facilitator group

4.5.5 Special Membership Groups

Technical Committee

Architecture Working Group

Advisory Board

• Strategic Governance Committee

• Governance Committee

4.6 Consensus building in Working Groups

Draft should specify that consensus building should prioritise consensus by deliberation and recommends a voting-based mechanism that can be activated whenever consensus by deliberation was not achieved and a decision has been made

5. Specifications

What is a specification

Scope of the GovStack architecture should be referenced here

5.1 Types of specifications

Map types of specs to this chart

1. Foundational BB

2. Feature BB

3. Guidelines

4. Cross-Cutting - Other types of requirements

5.2 Lifecycle of a specification and its processes

Specifications are meant to be proposed, drafted, reviewed, released, implemented, improved-on through feedback, and whenever needed, obsoleted. The GovStack community and its governance provides the environment to all of these stages.

Open

The Specification Lifecycle and the teams involved in each stage

Working Groups are the places where most of this happens.

The following are processes and procedures available to Working Groups that work on specification building:

Specifications Track Process: The process that describes the high-level procedure to move specifications from Proposal, Draft, Review, Publish and Obsoleting. It clarifies who performs, who facilitates and who reviews and who approves each part of the process.

Specification Review Process: The procedures that helps Working Groups coordinate the review process of a specification.

5.3 Specifications Track Process

5.3.1 Specifications Track

A specification, no matter if its a new specification or a new major version, goes through the following stages for publication:

1. Specification Proposal

2. Specification Draft

3. Specification Release Candidate

4. Published Specification

5. Obsoleted specification

Minor versions can skip the Specification Proposal Phase and undergo an internal review process by the Working group.

5.3.2 Tools for crafting specifications

The following are tools a working group should have access to, through its facilitators, and the usage expected out of these tools. Access can be requested to the Technical Facilitation Team:

5.3.3 Roles

In a nutshell:

In detail:

Governance Committee:

1. Approves the proposal for the creation of new specifications

2. Approves a proposal for major version of a specification

3. Gets notified of the creation of a minor version

4. Gets notified of the undergoing of the Release Candidacy or the Publishing for a specification

5. Approves the obsoleting of a specification

Technical Facilitation Team

1. Ensures proposals for new specifications or major version of specifications are complete, sound and properly estimated, and pass a Product and Technical soundness review.

2. Is responsible for green-lighting moving any specifications from one step to the next on the Specifications Track Process by ensuring readiness of the process.

3. Coordinates the Release Process, including the different aspects of the review and publishing process.

4. Provides facilitation support to Working Groups and any support regarding tooling, technical writing and review, as well as networking needed to advance either specifications being built or activities supported on the Working Group’s Charter.

5. Identifies any needs for human or material resources for both specification work and working group charter activities and works to present budget proposals to the Governance Committee.

Architecture Working Group

1. Reviews that proposals for new specifications or major version of specifications reflect the state of the art for that technology, that the proposal reflects the principles outlined in the Architecture and Nonfunctional Requirements of the GovStack Initiative, and that it is harmonious and not overlapping with the rest of the Building Blocks ecosystem.

2. Ensures proposals for new specifications or major version of specifications are reviewed and green lighted with the Product Committee and teams and groups related to it. This is called Product Soundness Review.

3. Ensures proposals and drafts for new specifications or major version of specifications pass a Architectural Soundness Review, by identifying the different groups and stakeholders that could provide feedback and clarify that the scope of the document makes technical sense, and ensuring it aligns to the rest of the GovSpecs ecosystem.

4. Presents proposals for new specifications or major version of specifications, as well as obsoleting of specification requests to the Governance Committee for approval. In the case of minor versions, it notifies the Governance Committee.

Working Groups

Through its Facilitators are responsible for the following activities

• Craft a Specification Proposal

• Update Working Group’s Charter with the Specification Proposal outlines and estimated timelines

• Coordinate Working Group Meetings where specification drafting activities are defined and deliberated, documenting meeting minutes in the Working Group’s Confluence space

• Own the Specification Drafting Process, and coordinate all work to be done through the Working Group’s Jira Space, as well as use the Working Group’s Confluence space for the Draft

• Decide, via deliberation, when a Specification is ready to be moved to a Release Candidate stage

• Request any help or resources needed from the Technical Committee Facilitation Team to complete the specification

Through its representatives, are responsible for the following:

• Present the Specification Proposal Document to the Technical Committee Facilitation Team and to the Architecture Working Group

• Attend Architecture Working Group Meetings to identify harmonious interaction with other building blocks

• Report progress of the Specification Drafting stage to the Technical Committee Facilitation Team

Through its members, are responsible for the following:

• Attend Working Group meetings where issues are deliberated and tasks are assigned

• Grab tasks from Jira to be worked-on for the drafting of the specification, and work on the Working Group’s Confluence space during the specification drafting stage

5.3.4 Moving through the stages of each part of the process

5.4 Specification Review Process

5.4.1 The stages and tasks of the Review Process

The Working Group owns the Review process, and aids itself with the help of the Technical Facilitation Team and the Architecture Working Group to perform it. The review has the following stages:

5.4.2 Quality Guidelines for the Release Process

• Sections

• Versioning

• Declaring dependency to other BB and their versions

• Change management

• Road-mapping

• Styles manual

• Referencing external specifications

5.4.3 Minimum Requirements for the Review Process

Each Working Group has autonomy in defining when to move a specification into a Release Candidacy, receive and integrate reviews and veredict for publishing. However, the following requirements MUST be observed:

1. The decision for moving a specification to a release candidacy, as well as the integration of feedback and veredicting of the Release Process MUST adhere to be decided using Consensus first, and resort to voting mechanisms where the need for agility in decision-making is required.

2. Release Notes should accompany every major version for a specification. Minor versions should be appended on a Changelog section of the release notes.

3. Reviews SHOULD be open to the public. However, the minimum threshold for reviewers should be no smaller than 2, and MUST NOT include neither members appearing in the credits section of the specification, or people belonging to the organization of the list of active members of the working group. For more detail, review the section for Determining Working Group Membership.

5.5 Using and improving specifications

After a specification has been officially released, it becomes important to promote and document its implementation. GovStack has several channels from which specification usage is promoted, tracked, tested and expanded. The following is a list of GovStack programmes and ways in which Working Groups have the right to interact:

5.6 Obsoleting a specification

At times a specification may become obsolete. It pertains the Working Group, the Technical Committee and, if needed, the advisory of other GovStack governance committees, to determine when a specification needs to be obsoleted. It is however through the triggering of the Obsoleting process by the Working Group and the review of the Technical Facilitation Committee that such process, described in section 5.3, happens.