...

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 https://govstack.gitbook.io/specification/architecture-and-nonfunctional-requirements/introduction.

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

• Govstack Building Block Cookbook

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

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

• The Meta Standard - Research

Working Groups

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

• https://adr.github.io/

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

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

...

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

• MembersMembers (volunteers, potentially remunerated for specific contributions): 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.

• LeadsRepresentative (volunteers, potentially remunerated for time investment): One or two people per working group who agree to the responsibility of representing the Working Group interests within the wider GovStack governance. Leads Representatives will be the main Points of Contact for a Working Group to report advances progress on the annual goals of a charter. WG representatives are expected (esp. from Foundational Building Blocks) to represent their group in the Architecture Working Group who decides upon the cross-functional requirements. 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 representatives will be the parties through which the Working Group will report its advances.

• Facilitators (remunerated for time investment): 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

• Technical Writer (optional role, remunerated for time investment)

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.

...

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:

...

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

• Agree to the Code of Conduct

• Individual Participation

• Individuals representing a member organization

4.5.5 Special Membership Groups

...

• Strategic Governance Committee

• Governance Committee

...

5. Specifications

What is a specification

Scope of the GovStack architecture should be denoted 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

...

Request:

• SHOULD contain a need

• SHOULD contain a scope

• MAY contain an outline

...

Draft

...

New version

...

Implementation cycles

1. Has a commited time to deliver a RFC

   1. This can be recommited with a TC

2. Has maximum time before archived

3. Is drafted by a WG. If a draft was submitted upon

Tools and what are they for:

• GitBook

• Github

• Jira

• Confluence

• Slack

• Swagger

  • Reference: https://govstack-global.atlassian.net/wiki/spaces/~615604c2bfa2c1006b775001/pages/1070235652/Fixing+links+in+marketplace#General-insights-about-the-Specs-procedure

  • About API documentation:

    • We should own a platform (swaggerhub, most likely) to manage and handle changes to guiding API’s

    • We need more control over changes to API procedures. Either we should have a standard procedure to handle exports (resolved vs unresolved) and changes. Or we should point the gitbook swagger blocks to our own GovStack owned swagger instance to avoid duplicity in Gitbook (this would be my preferred way). That would mean the APIs in SwaggerHub would also need to be versioned, mimicking version numbers on GitBook.

• Figma

• General info for each tool:

  • URL’s

  • Roles and access procedures for each

  • Related processes

  • Public documents

Changes:

• Roles:

  • Mantainers

  • Editors

• Submit a change

  • Deprecation notices should be specified whenever a numeral goes obsolete and a deprecation change log attached

Sections:

Requesting the creation of a specification

...

A specification can be requested by a Working Group or

Requirements for a specification

...

A Specification Draft is assigned to a Working Group

...

Drafting phase

• Methodology to produce a draft

• Organizational requirements to produce a draft

• Tools and funds to produce a draft

...

Assurance phase

• Feedback loops

• Implementers

...

Publishing phase

...

Roadmapping

...

Versioning

...

Obsoleting

• Specifications

• Guidelines

• Policies? Implementation

• Sector specific specifications

Tools and requirements for specification teams

Glossary

Charter

The GovStack model

...

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.

...

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 Specification Track Process

...

Specifications go through the following phases:

1. A Proposal Document, which broadly describes the intention

5.3.1 Roles

5.3.2

• 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