1. 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 2 Introduction | GovStack Specification.

2. Updates

This document is meant to update the following documents:

• Specification Development Roles and Processes

• Scope and Overall Principles

• Roles

• GovStack Quality Criteria

• Publication cycles

3.1 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

• Adaptor Concept

• Building Block Working Groups

• Charter

3.1.2 External

• W3C Process Document

• W3C Recommendation Track Readiness Best Practices

• Architectural Decision Records (ADRs)

• 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 thought 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:

• Facilitators: The team tasked with the responsibility of organizing all of the Working Group activities. Having a group of facilitators allows for the WG leads 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

• 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.

• Leads: One or two people per working group who agree to the responsibility of representing the Working Group interests within the wider GovStack governance. Leads will be the main Points of Contact for a Working Group to report progress on the annual goals of a charter. If a Working Group want to submit a proposal for the creation of a new specification or on the creation of a iteration for a new version, major or minor, of an existing specification, as well as a request to obsolete an existing specification, the WG Leads will be the parties through which the Working Group will report its advances.

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.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

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 who owns each stage

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

Open

The Specifications Lifecycle and its processes

Another version for this graph (feedback welcome on which is best):

Open

The Specification Lifecycle and the teams involved in each stage

5.2.1 Proposing a new specification

Working Groups are the places where proposals for new specifications happen. While the idea for a new specification may come from another GovStack organ or even an external group or organization, it is within the Working Groups and through their tooling such as their meetings, their Annual Charter, and their organization, where the crafting of the specification is built. The following are stages of building a specification that a Working Group is vested with:

• Coming up with a Proposal Document

• The process in which a Specification Draft is crafted

• The determination of when a Draft is ready for review to become a Release Candidate

5.2.2 Reviewing and Releasing a specification

After a Working Group has thoroughly worked through a specification with the aid of meetings, the Specification Release Manual and validation from experts, and determine it is ready for review, they trigger the release process by turning the Draft into a Release Candidate. The Release Process is owned by the Technical Committee and it is further discussed in section 5.3 The Release Process.

5.2.3 Using existing 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 Country Engagement Team

• GovMarket

• GovTest

• GovLearn

• GovStack Digital Leaders Forum

The different programmes and offerings naturally generate feedback loops regarding the specifications that can be inputs to improve them.

5.2.4 Improving existing specifications

From the usage, testing and implementation of the specifications, it may become necessary to amend a specification, expand it by adding more features to it, or deprecating a section. Working Groups are the spaces where people can convene to determine when that is the case. They do that by proposing a new minor or major version of the specification and triggering a new release process.

5.2.5 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.

5.3 The release process

5.3.1 Roles

• Propose a new major or minor version

• Change management

• Deprecate a section properly

• Submitting a release candidate

• The review process

  • Quality Review

  • Technical Review

  • Implementability Review

• Veredicting

  • Receiving Feedback

• Publication

5.4 Release quality criteria

• Sections

• Versioning

• Declaring dependency to other BB and their versions

• Change management

• Road-mapping

• Styles manual

• Referencing external specifications

5.5 Tools for developing and publishing specifications

• GitBook

• Github

• Jira

• Confluence

• Slack

• Swagger

• Figma

• General info for each tool:

  • URL’s

  • Roles and access procedures for each

  • Related processes

  • Public documents

6. Glossary of terms

GovStack Organs

GovStack Governance Groups