chore: add Governance procedures (#108)

* 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
This commit is contained in:
Fabio Bonelli 2021-12-13 17:23:09 +01:00 committed by GitHub
parent 9996103255
commit 0af1904ca3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 220 additions and 65 deletions

2
CODEOWNERS Normal file
View File

@ -0,0 +1,2 @@
/docs/en/ @publiccodeyml/steering-committee
/governance/ @publiccodeyml/steering-committee

View File

@ -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.
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.
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).
# In short
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 [**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.
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.
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.
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.
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.
If your documentation and code have passed human review, it is merged.
Other contributors (or helper robots) might have feedback.
If this is the case, the reviewing maintainer will help you improve the Pull Request.
If your documentation or code have passed human review, it is merged.
### 4. Celebrate
Your ideas, documentation and code have become an integral part of this project. You are the Open Source hero we need!
Your ideas, documentation and code have become an integral part of this project.
You are the Open Source hero we need!
In fact, feel free to open a PR to add your name to the [`AUTHORS`](AUTHORS.md) file and get eternal attribution.
---
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.

View File

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

View File

@ -1,7 +1,7 @@
.. _`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
@ -9,9 +9,9 @@ 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.

View File

@ -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``
~~~~~~~~~~~~~~~~

51
governance/charter.md Normal file
View File

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

View File

@ -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!