chore: add Governance procedures (#108)

bfabio · web-flow · commit 0af1904ca3a3 · 2021-12-13T17:23:09.000+01:00
* chore: add Governance procedures

* chore: add German Committee member

* chore: update CONTRIBUTING.md to the new flow

* chore: update README.md

* chore: uniform the Country specific section part in the Standard
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -0,0 +1,2 @@
+/docs/en/ @publiccodeyml/steering-committee
+/governance/ @publiccodeyml/steering-committee
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,51 +1,98 @@
-# Contributing to this standard
+# Contributing to this Standard
 
-🙇‍♀️ Thank you for contributing!
+Thank you for your interest in contributing! 🙇
 
-We – the maintainers and contributors of this project – understand that a standard like this can only be set in collaboration with as many public technologists, policy makers and interested folk as possible. Thus we appreciate your input, enjoy feedback and welcome improvements to this project and are very open to collaboration.
+We – the maintainers and contributors of this project – understand that a Standard
+like this can only be set in collaboration with as many public technologists,
+policymakers and interested folks as possible. Thus, we appreciate your input, enjoy
+feedback and welcome improvements to this project and are very open to collaboration.
 
 We love issues and pull requests from everyone.
 
-## Problems, suggestions and questions in Issues
-
-Please help development by reporting problems, suggesting changes and asking questions. To do this, you can [create a GitHub Issue](https://help.github.com/articles/creating-an-issue/) for this project in the [GitHub Issues for publiccode.yml](https://github.com/italia/publiccode.yml/issues).
+## I want to help develop the standard
 
+Please help development by reporting problems, suggesting changes and asking questions.
 You don't need to change any of our code or documentation to be a contributor!
 
-## Documentation and code in Pull Requests
+Anyone is welcome to participate!
 
-If you want to add to the documentation or code of one of our projects you should make a Pull Request. 
+The best ways to do so are:
+* [Participate in discussions](https://github.com/publiccodeyml/publiccode.yml/discussions)
+* Once you know your contribution is ready, [open a pull request](https://github.com/publiccodeyml/publiccode.yml/pulls)
 
-If you never used GitHub, get up to speed with [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/) or follow one of the great free interactive courses in the [GitHub learning lab](https://lab.github.com/) on working with GitHub and working with MarkDown, the syntax this project's documentation is in.
+## I am a Free Software developer
 
-This project is [licenced CC-0](LICENSE), which essentially means that the project, along with your contributions is in the Public Domain in whatever jusrisdiction possible, and everyone can do whatever they want with it.
+Help us bring new Free Software into governments!
+You can add a `publiccode.yml` file in your repositories, ask other projects to do it,
+or, even better, help us create tools.
 
-### 1. Make your changes
+Don't be afraid to start new ones and
+[show them to the community](https://github.com/publiccodeyml/publiccode.yml/discussions/categories/show-and-tell).
+
+## I am a public software vendor
+
+Add a `publiccode.yml` file to your repositories!
+After that, you can submit it to national catalogs, for example:
+
+* [Developers Italia](https://github.com/italia/developers-italia-backend)
+* ...
+
+## I am a public servant and want to represent my country in the Steering Committee
+
+We are happy to have you here!
+
+[Take a look at the Charter](/governance/charter.md) and, once you made sure you are
+the right person, please [create a new post](https://github.com/publiccodeyml/publiccode.yml/discussions/categories/general).
+
+The Chair will get in touch with you and get you started.
 
-This project uses the [**GitFlow branching model** and workflow](http://nvie.com/posts/a-successful-git-branching-model/). When you've forked this repository, please make sure to create a feature branch following the GitFlow model.
+We strongly encourage you to also contribute translations (if applicable) and, if needed,
+[a national section](https://yml.publiccode.tools/country.html).
+Just make your changes and [submit a Pull Request](https://github.com/publiccodeyml/publiccode.yml/pulls).
 
-Add your changes in commits [with a message that explains them](https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message). Document choices or decisions you make in the commit message, this will enable everyone to be informed of your choices in the future.
+# In short
 
-If you are adding code, make sure you've added and updated the relevant documentation and tests before you submit your pull request. Make sure to write tests that show the behaviour of the newly added or changed code.
+If you never used GitHub, get up to speed with [understanding the GitHub Flow](https://guides.github.com/introduction/flow/)
+or follow one of the great free interactive courses in the
+[GitHub learning lab](https://lab.github.com/).
+
+This project is [CC-0 licensed](LICENSE), which essentially means that the project, along
+with your contributions, is in the Public Domain in whatever jurisdiction possible, and
+everyone can do whatever they want with it.
+
+### 1. Make your changes
+
+This project uses the [**GitHub flow branching model**](https://docs.github.com/en/get-started/quickstart/github-flow).
+
+Add your changes in commits [with a message that explains them](https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message).
+Document choices or decisions you make in the commit message, this will enable everyone to
+be informed of your choices in the future.
 
 ### 2. Pull Request
 
-When submitting the pull request, please accompany it with a description of the problem you are trying to address and the issue numbers that this Pull Request fixes/addresses.
+When submitting the pull request, please accompany it with a description of the problem
+you are trying to address and the reference to the relevant Issue or Discussion.
+
+If your Pull Request is about a part of the Standard or the Governance of the project,
+it's considered as a formal proposal and will be voted on,
+[following this procedure](/governance/procedure-proposing-changes-and-voting.md).
 
 ### 3. Improve
 
 All contributions have to be reviewed by someone.
 
-It could be that your contribution can be merged immediately by a maintainer. However, usually, a new Pull Request needs some improvements before it can be merged. Other contributors (or helper robots) might have feedback. If this is the case the reviewing maintainer will help you improve your documentation and code.
-
-If your documentation and code have passed human review, it is merged.
+It could be that your contribution can be merged immediately by a maintainer.
+However, usually, a new Pull Request needs some improvements before it can be merged.
 
-### 4. Celebrate
+Other contributors (or helper robots) might have feedback.
+If this is the case, the reviewing maintainer will help you improve the Pull Request.
 
-Your ideas, documentation and code have become an integral part of this project. You are the Open Source hero we need! 
+If your documentation or code have passed human review, it is merged.
 
-In fact, feel free to open a PR to add your name to the [`AUTHORS`](AUTHORS.md) file and get eternal attribution.
+### 4. Celebrate
 
----
+Your ideas, documentation and code have become an integral part of this project.
+You are the Open Source hero we need!
 
-For more information on how to use and contribute to this project, please read the [`README`](README.md).
+In fact, feel free to open a Pull Request to add your name to the [`AUTHORS`](AUTHORS.md)
+file and get eternal attribution.
diff --git a/README.md b/README.md
@@ -73,31 +73,10 @@ This project follows the Semantic Versioning.  For more information see
 [SemVer.org](https://semver.org/).
 
 Furthermore, the project uses branches and tags in the following way:
-* The `master` branch contains the latest stable version of the standard.
-* The `development` branch contains the improvements proposed for the next
-  version. 
+* The `main` branch contains the improvements coming up in the next version.
 * GitHub's [release page](https://github.com/italia/publiccode.yml/releases)
-  contains all the released versions of the standard. Releases are done
-  following the tag version for consistency.
-
-However, since the repository contains both the core schema and the
-country-specific ones, it is necessary to further refine the versioning. 
-As such, each update at the core and/or to a country-specific extension will be
-tagged as follows:
-
-> core-x.y.z;cc-a.b.c
-
-where cc is the country code defined in the `countryExtensionVersion` key. 
-
-This versioning schema is fundamental in this project since the
-`publiccode.yml` file contains references to the core release in the
-`publiccodeYmlVersion` key and each country-specific schema contains
-a `version` key. 
-
-Examples of this versioning schema may be:
-
-> * core:0.2;it:0.4
-> * core:0.2;fr:1.1
+  contains all the released versions of the standard. Releases are tagged
+  with the Standard's version.
 
 ## Contributing
 
diff --git a/docs/en/country.rst b/docs/en/country.rst
@@ -1,17 +1,17 @@
-.. _`country-extension`:
+.. _`country-section`:
 
-Country-Specific Extensions
-===========================
+Country-Specific Sections
+=========================
 
 While the standard is structured to be meaningful on an international
 level, there are additional information that can be added that makes
 sense in specific countries, such as declaring compliance with local
 laws or regulations. The provided extension mechanism is the usage of
 country-specific sections.
 
-All country-specific extensions are contained in a section named with
-the two-letter lowercase `ISO 3166-1 alpha-2 country
-code <https://it.wikipedia.org/wiki/ISO_3166-1_alpha-2>`__. For instance
+All country-specific sections live under a key named after two-letter
+lowercase `ISO 3166-1 alpha-2 country
+codes <https://it.wikipedia.org/wiki/ISO_3166-1_alpha-2>`__. For instance
 ``spid`` is a property for Italian software declaring whether the
 software is integrated with the Italian Public Identification System.
 
@@ -20,11 +20,11 @@ If a software is compliant I will find:
 .. code:: yaml
 
    it:
-     countryExtensionVersion: "0.2"
+     countryExtensionVersion: "1.0"
      piattaforme:
       - spid: yes
 
-Notice that country-specific extensions within international sections
+Notice that country-specific keys within international sections
 are not allowed. Countries that want to extend the format should add a
 country-specific section instead.
 
diff --git a/docs/en/schema.it.rst b/docs/en/schema.it.rst
@@ -1,9 +1,9 @@
-.. _italian-extensions:
+.. _italian-sections:
 
 Italy
 -----
 
-All the extensions listed below are specific for Italy and, as such, they must
+All the keys listed below are specific for Italy and, as such, they must
 be inserted in a section named with the ``it`` code. Every Country is specified
 using a two letters *country code* following the ISO 3166-1 alpha-2 standard.
 
@@ -13,16 +13,10 @@ Key ``countryExtensionVersion``
 
 - Type: string
 - Presence: mandatory
-- Example: ``"1.0"``
+- Value: ``"1.0"``
 
 
-This key specifies the version to which the current extension schema adheres to,
-for forward compatibility.
-
-Please note how the value of this key is independent from the top-level
-``publiccodeYmlVersion`` one (see :ref:`core`). In such a way, the extensions
-schema versioning is independent both from the core version of the schema and
-from every other Country.
+This key **MUST** always be set to ``1.0``.
 
 Key ``conforme``
 ~~~~~~~~~~~~~~~~
diff --git a/governance/charter.md b/governance/charter.md
@@ -0,0 +1,51 @@
+# publiccode.yml Working Group Charter
+
+The publiccode.yml Working Group is a community of people with the common goal of evolving and
+maintaining the publiccode.yml Standard.
+
+We welcome contributions by everyone, in the form of Pull Requests.
+
+To ensure the development of the project is always aligned to the needs of public agencies, we set
+up a [Steering Committee](#steering-commitee) composed solely of public servants.  The Committee is
+tasked with the formal voting required to evolve the core Standard.
+
+All other tools are community-maintained.
+
+## Steering Committee ([@publiccodeyml/steering-committee](https://github.com/orgs/publiccodeyml/teams/steering-committee))
+
+* 🇩🇰 Denmark: [@zorp](https://github.com/zorp) for OS2 Offentlig Digitaliseringsfællesskab
+* 🇫🇷 France: [@bzg](https://github.com/bzg) for Etalab (Direction interministérielle du numérique)
+* 🇩🇪 Germany: [@cknebel](https://github.com/cknebel) (publicplan GmbH)
+* 🇮🇱 Israel: [@ShimonShore](https://github.com/ShimonShore) (Israel Ministry of Science and
+  Technology)
+* 🇮🇹 Italy: [@ruphy](https://github.com/ruphy) for DTD (Presidenza del Consiglio dei Ministri)
+
+The Steering Committee members can vote on proposals on Pull Requests, the workflow is detailed in
+[procedure-proposing-changes.md](procedure-proposing-changes-and-voting.md#voting)
+
+We don't have strict rules, as every country is different, but suggest that the appointed member
+should be part of a central entity managing software or technological innovation at the government
+level.
+
+# Roles and duties
+
+### Chair ([@ruphy](https://github.com/ruphy))
+
+* Plans, organizes agenda and moderates meetings
+* Prepares and shares milestones and deadlines
+* Oversees the voting procedure
+* Is the ultimate responsible for the development of the project
+* Has administrative access on GitHub and other platforms
+
+### Maintainer ([@bfabio](https://github.com/bfabio), [@sebbalex](https://github.com/sebbalex))
+
+* Maintains the non-Standard side of repositories
+* Merges PR regarding the Standard after consensus by the Steering Committee
+* Has administrative access to the repositories
+
+### Non-voting member (None)
+
+* Attends Steering Committee meetings
+
+Active members from the community may be invited as non-voting members with the approval of at
+least the majority of the Steering Committee.
diff --git a/governance/procedure-proposing-changes-and-voting.md b/governance/procedure-proposing-changes-and-voting.md
@@ -0,0 +1,82 @@
+# Proposing changes
+
+Everyone can propose changes to the Standard ([`/docs/en/`](/docs/en/)) or organization of the
+Working Group ([`/governance/`](/governance/)).  Every other part of the repo, including
+translations of the Standard, are not normative and don't undergo this procedure.
+
+Proposals and high level ideas can be discussed in [GitHub
+Discussions](https://github.com/publiccodeyml/publiccode.yml/discussions) (or [GitHub
+Issues](https://github.com/publiccodeyml/publiccode.yml/issues) if you think the proposal is
+straightforward) but are only officially considered once a Pull Request is submitted as [a Pull
+Request directly on the GitHub repository](https://github.com/publiccodeyml/publiccode.yml/pulls).
+
+The participation in the discussion is encouraged and is free and open to everyone, as is the
+submission of Standard-changing Pull Requests.
+
+The [Maintainers](https://github.com/orgs/publiccodeyml/teams/steering-committee) are responsible
+for labelling any change depending on their nature according to the [Semantic
+Versioning](https://semver.org/), or in other words:
+
+* [**`standard-fix`**](https://github.com/publiccodeyml/publiccode.yml/labels/standard-fix): for all
+  changes that don't break any compatibility, warrants a new patch version
+* [**`standard-backward-compatible`**](https://github.com/publiccodeyml/publiccode.yml/labels/standard-backward-compatible),
+[**`standard-deprecation`**](https://github.com/publiccodeyml/publiccode.yml/labels/standard-deprecation):
+  for all changes that are retrocompatibile, warrants a new minor version
+* [**`standard-breaking-change`**](https://github.com/publiccodeyml/publiccode.yml/labels/standard-breaking-change):
+  for all changes that break retro-compatibility, warrants a new major version.
+  Breaking changes can be released at most once every two years, provided the current
+  version of the Standard has been deprecating the relevant feature for at least 6 months.
+  
+## Voting
+
+To ensure the Standard always keeps aligned to the needs of public administrations, we encourage
+participation from everyone but restrict the voting to public servants, for this reason voting is
+only open to members of the [Steering Committee](charter.md#steering-commitee-publiccodeymlsteering-committee),
+typically one per country.
+
+[The Chair](charter.md#roles-and-duties)  of the Steering committee is responsible for holding a
+regular vote, which happens as deemed necessary. Once the voting starts, it stays open for a week.
+
+Voting happens on formal proposals opened as Pull Requests through expressing a clear intention to
+*approve*, *reject*, or *abstain*.  This can be done by either using GitHub's code review feature,
+or as a simple comment to the Pull Request.  Only *approve* or *reject* votes are used to determine
+the results.
+
+Proposals require unanimity to pass, but when that doesn't happen, proposals with at least 50%
+*approve* votes get discussed for an additional period of minimum of 90 days, after which they are
+put again to vote. In this second round, the change only needs 75% *approve* votes in order to be
+considered accepted.
+
+### Country-specific sections
+
+Changes to country-specific sections (top level keys named after [ISO 3166-1 alpha-2
+codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) and their children) always require the
+*approval* of the Steering Committee member representing the corresponding country and 50% *approve*
+votes.
+
+Besides that, they must follow the format used in the rest of the Standard, in particular:
+* key names must be lowerCamelCase
+* key names must use only uppercase or lowercase ASCII letters
+* use English for keys and values, when possible
+* must not mimic or duplicate other existing top level keys
+
+In practice, we expect members of other countries to abstain unless there's a good reason not to do
+so.
+
+### Results of the vote and implementation of the changes
+
+After a week from the vote has passed, the Chair formally announces the results.
+
+The Maintainers act accordingly to reflect the changes on GitHub and proceed to queue the changes in
+the next release cycle.
+
+# Releasing
+
+Changes are batched and released at most monthly if there are approved proposal in the queue.
+
+# Calls and meetings
+
+No calls and meetings are scheduled. If the need arises for a community call, a technical call, or a
+meeting of the Steering Committee, an [announcement will be made in this
+category](https://github.com/publiccodeyml/publiccode.yml/discussions/categories/announcements).
+Make sure you watch it, so you don't miss any notifications!

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+/docs/en/ @publiccodeyml/steering-committee`
	`2`	`+/governance/ @publiccodeyml/steering-committee`