...
| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
...
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.
Updates
This document is meant to update the following documents:
References
Internal
External
Working Groups
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.
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.
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 advances 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.
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 may 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.
...
Working Group Creation and
...
Becoming a member and membership finalization
Process for becoming a lead
How leads are funded
Specifications
What is a specification
Scope of the GovStack architecture should be denoted here
Check with Kristo:
GovStack is a Framework for interoperability
The framework is composed of components:
https://govstack.gitbook.io/specification/architecture-and-nonfunctional-requirements/3-govstack-architecture
Applications (whatever a government has, DPGs)
Building Blocks: Standards for use cases that set the bar on how different feature services must be delivered
Protocol tools: Building-Blocks, Adaptors, Information Mediator, Workflows. The different pieces that GovStack proposes and governs for which interoperability for existing IT platforms and ecosystems can be achieved.
Building Block software: Any software that complies with the BB standard
Foundational BB
Feature BB
Cross-Cutting - Other types of requirements
Request:
SHOULD contain a need
SHOULD contain a scope
MAY contain an outline
Draft
New version
Implementation cycles
Tools and what are they for:
GitBook
Github
Jira
Confluence
Slack
Swagger
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
...
the creation of the Annual Charter
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.
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.
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.
Becoming a member and membership finalization
| Info |
|---|
Work in progress |
Who is a participant
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
Special Membership Groups
| Info |
|---|
Work in progress. Search for existing documents describing these groups or organs. |
Technical Committee
Architecture Working Group
Advisory Board
Strategic Governance Committee
Governance Committee
...
Specifications
| Info |
|---|
Work in progress |
What is a specification
Scope of the GovStack architecture should be referenced here
Types of specifications
Map types of specs to this chart
Foundational BB
Feature BB
Cross-Cutting - Other types of requirements
Roles
Lifecycle of a specification
Specifications are meant to be proposed, drafted, reviewed, released, implemented, and improved or obsoleted. The GovStack community and its governance provides the environment to all of these cycles.
...
Propose a new specification
Proposal Document
Draft
Release candidate
Using existing specifications
Implement
Feedback loops
Improving existing specifications
Request a new version
Change management
Deprecate a section properly
Obsolete a specification
The release process
| View file | ||
|---|---|---|
|
Submitting a release candidate
The review process
Quality Review
Technical Review
Implementability Review
Veredicting
Receiving Feedback
Publication
Release quality criteria
Sections
Versioning
Change management
Road-mapping
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