From b60681fcb8120ca59fc4c32f9d4d2332b39f1712 Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Fri, 17 Jun 2022 14:57:42 +0100 Subject: Agreement on a governance model for thin-edge MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Didier Wenzek Signed-off-by: Marcel Müller --- GOVERNANCE.md | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 GOVERNANCE.md diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 00000000..22ab8d9a --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,118 @@ +# Governance thin-edge.io + +This documents servers as a guiding document to ease technical decision making in the project as a whole. + +Some of its goals are: + +- Making sure that the different stakeholders are represented with their requirements +- Making sure that contributors know how decisions are made and who they can address concerns/questions to +- Making sure that team members know what is required of them for the project + + +## The project vision + +In the [vision.md](./vision.md) the goal of the project is encoded. +It specifies the different functional requirements and non-functional requirements of the project as a whole. +All the stakeholders must agree on the vision upon joining. + +- The current stakeholders are: Software AG, and IFM + +Changes to the vision need to be done in a plenum of stakeholders, this makes sure that everyone is aware and agrees to the evolution of the project. + + + +## Team Structure + +* Teams are either single contributors or a group of them +* They are responsible for a specific part of project, and as such are the maintainers of those parts + * This includes: Reviewing pull requests, triaging issues assigned to them, and general maintenance +* Each team is assigned a single or multiple subtrees of the project, as defined by the project structure +* The teams follow the project hierarchy for decisions, i.e. higher decisions take precedence + +The important bits: + +At the top, each invested party has their representative, who together with the others in their group have to come to conclusions together. These should be based on the following factors: + +- The signed off vision of the whole project +- Feasability, accounting for future technical and cultural shifts +- The health of the project going forward + +Overall, these 'project leads' should not be beholden to their respective companies, and instead to the health of the project and its community. + +Underneath the leads are the teams or individuals, that each are allowed to make similar decisions about the project *in the area they have been delegated*. + + +- Some decisions are global in the project, like the core/API + - Team members should try and make sure to explore possible options together before calling for a vote. This mostly includes uncontroversial changes that are low impact or have already been agreed upon + - If this is not possible, a vote needs to be held: TODO + +- Some decisions are local, e.g. a plugin does not impact others with its behaviour, however it still needs to be a 'good citizen' in the project (CI, format, etc..) + - These should be clearly scoped in their respective project part + - However, if needed a 'higher up' decision can be requested if no consensus is achieved + + + +## Project Structure + +The project has a hierarchy to solve these two problems: + +1. How can participating organizations make sure that their voice and interests are represented in the project? + - Each member party appoints one core team member + - They form the group of people that have to, and are responsible for, signing off on the technical implementation of the project +2. How to make the lives of these team members easier? + + +----- + +* Thin-edge is organized around sub-projects - to ease decision taking. + * The sub-projects are organized in a hierarchy + * This makes it easier to decouple different parts of the project + * This makes it easier to decide on technical questions + * Everyone has to agree on the core project bringing the foundations to all others. + * At the periphery, sub-projects might be related to specific eco-systems (e.g. Cumulocity or Moneo) and therefore have independent decision processes. + * At an intermediate level, one might have sub-projects related to specific use-cases like “JSON over MQTT”. +* All the sub-projects share a common repository - to ease consistency across projects and over time. + * Labels are used to organize issues/PRs/discussions along sub-projects. + * Code ownership is used to enforce cooperation around key components, but the default is to let things open and to trust each other, using version control as a safety net. + + + + + + +``` +core contributors = [SAG, IFM] + +-> Project leads, one each from [core contributors] +| + \- Responsible for `/*`, aka everything in the repository + | + | + \ + \-> Delegated project Teams, any combination of [teams, individual contributors] + | + |\- Responsible for `/plugins/plugin_{foo,bar}` + ||- Are trusted by the project leads (who would have to stand-in for the trusted members) + | + |-> Can be needed to nest further if the project grows bigger +``` + +## Repository maintenance + + +- clear commits +- Ensuring the Signed-off-by-trailer +- coding styleguide +- testing +- benchmarks +- documentation builds +- keeping spec up to date +- merge strategies +- evergreen master +- Dependency updates +- License linting + +## Related + +* [Understanding open source governance models](https://www.redhat.com/en/blog/understanding-open-source-governance-models) +* [Producing Open Source Software](https://producingoss.com/en/producingoss.html) \ No newline at end of file -- cgit v1.2.3 From 397b0cba12d2ca92b6fd983ac1bbad319bc71fa0 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 22 Jun 2022 10:18:36 +0200 Subject: Add content for signed-off-by-trailer section Signed-off-by: Matthias Beyer --- GOVERNANCE.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 22ab8d9a..fa5e459b 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -102,6 +102,17 @@ core contributors = [SAG, IFM] - clear commits - Ensuring the Signed-off-by-trailer + Contributors need to sign the "Contributor License Agreement". They do so by + signing off each individual commit with a so-called "Signed-off-by Trailer". + Git offers the `--signoff`/`-s` flags when using `git-commit` to commit + changes. + + To ensure that all commits have the trailer present in the commit message, a + CI lint is installed in the github actions workflows of the project. This lint + blocks pull requests to be merged if one or more of the commits of the pull + request misses the `Signed-off-by` trailer. + + As a result, it is not possible to merge pull requests that miss the trailer. - coding styleguide - testing - benchmarks @@ -115,4 +126,4 @@ core contributors = [SAG, IFM] ## Related * [Understanding open source governance models](https://www.redhat.com/en/blog/understanding-open-source-governance-models) -* [Producing Open Source Software](https://producingoss.com/en/producingoss.html) \ No newline at end of file +* [Producing Open Source Software](https://producingoss.com/en/producingoss.html) -- cgit v1.2.3 From b72cfbf09a6a796f39a15df4b53b84f9fb35effa Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 22 Jun 2022 10:24:10 +0200 Subject: Add content for evergreen master section Signed-off-by: Matthias Beyer --- GOVERNANCE.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index fa5e459b..aae6ff7b 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -118,8 +118,14 @@ core contributors = [SAG, IFM] - benchmarks - documentation builds - keeping spec up to date -- merge strategies - evergreen master + The project pursues the "evergreen master" strategy. That means that at every + point in time, the commit that `master`/`main` points to must successfully + build and pass all tests successfully. + + Reaching that goal is possible because of the employed merge strategies (read + below). +- merge strategies - Dependency updates - License linting -- cgit v1.2.3 From 0b6739471d6c082dab9ec622b7e9a018885e6033 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 22 Jun 2022 10:46:14 +0200 Subject: Add content for "merge strategies" section Signed-off-by: Matthias Beyer --- GOVERNANCE.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index aae6ff7b..fbbd59dd 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -126,6 +126,47 @@ core contributors = [SAG, IFM] Reaching that goal is possible because of the employed merge strategies (read below). - merge strategies + Merging is the way how the project accepts and implements changes. + + Because of the pursued "everygreen master", merging is implemented in a + certain way that forbids several bad practices which could lead to a breaking + build on the `master`/`main` branch, and a special workflow is implemented to + ensure not only the "evergreen master" but also to streamline the workflow for + integrating pull requests. + + The following actions are **not** allowed: + + * Committing to `master`/`main` directly + * Squash-Merging of pull requests (which is equivalent to committing to + `master`/`main` directly). + The github repository is configured to not allow squash merges. + * Merging of "!fixup" or "!squash" commits. A github actions + job is employed to block pull requests from being merged if such commits are + in the PR branch. Rebase should be used to clean those up. + + It is explicitely _not_ forbidden to have merge-commits in a pull request. + Long-running pull requests that contain a large number of changes and are + developed over a long period might contain merges. They might even merge + `master`/`main` to get up-to-date with the latest developments. Though it is + not encouraged to have such long-running pull requests and discouraged to + merge `master`/`main` into a PR branch, the project acknowledges that + sometimes it is not avoidable. + + To summarize, the following requirements have to be met before a pull request + can be merged: + + * Reviews of the relevant persons (ensured via github setting) + * Status checks (CI, lints, etc) (ensured via github setting) + * builds, tests, lints are green (ensured via github action) + * Commit linting (ensured via github action) + * No missing `Signed-off-by` lines (ensured via github action) + * No "!fixup"/"!squash" commits in the pull request (ensured via github + action) + * Conversations must be resolved (ensured via github setting) + + Merging itself is implemented via a "merge bot": [bors-ng](https://bors.tech). + bors-ng is used to prevent "merge skew" or "semantic merge conflicts" + (read more [here](https://bors.tech/essay/2017/02/02/pitch/)). - Dependency updates - License linting -- cgit v1.2.3 From c09d8d0e0f2532b647339ef4abd6e6e6ca8c7f6e Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 22 Jun 2022 10:49:32 +0200 Subject: Add content for "coding styleguide" section Signed-off-by: Matthias Beyer --- GOVERNANCE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index fbbd59dd..453446de 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -114,6 +114,8 @@ core contributors = [SAG, IFM] As a result, it is not possible to merge pull requests that miss the trailer. - coding styleguide + Coding style is enforced via `rustfmt` in its default configuration. + Compliance with the coding style is enforced via CI. - testing - benchmarks - documentation builds -- cgit v1.2.3 From 16c7ac120ad53732e942710bea97a9a3d2b4283c Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 22 Jun 2022 11:07:48 +0200 Subject: Add content for "clear commits" section Signed-off-by: Matthias Beyer --- GOVERNANCE.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 453446de..4dec595d 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -101,6 +101,51 @@ core contributors = [SAG, IFM] - clear commits + Having clear, consise and well-written commit messages for all changes is not + only a indicator for the seriousness of the project, but also a way to ensure + sustainable development via replicability of the sources of the project. + + Because of this, we try to ensure the highest possible quality for each + individual commit message. + + Because such a thing cannot necessarily or in full be enforced via tooling, it + remains mainly the obligation of a reviewer of a changeset to ensure + + * Seclusiveness of the individual commits + * that one commit is one atomic change, and not an accummulation of several + individual and seperate changes + * that the commit message of the change expresses why the change was made + + Every reviewer of a pull request is asked to review not only the changes, but + also the commit messages. + Reviewers are explicitely empowered and actually encouraged to block pull + requests that contain commit messages that do not meet a certain standard + even and especially also if the proposed changes are acknowledged. + + The contributor should document why they implemented a change properly. A good + rule of thumb is that if a change is larger than 60 lines, a commit message + without a body won't suffice anymore. + The more lines are touched by an individual commit, the more lines should be + used to explain the change. + + The project implements lints using github actions to meet such criteria. + + Also, some hard criteria is checked via github action lints: + + * The `Signed-off-by` trailer lint must be present in all commits (also see + section "Ensuring the Signed-off-by-trailer") + * The commit body must meet the default formatting of a commit message, that + is + * Subject line not longer than 50 characters + * Subject capitalized + * No period at the end of the subject + * Imperative mood in the subject + * Second line empty + * Body lines not longer than 72 characters + + Commits using the `--fixup` or `--squash` feature of `git-commit` are allowed, + but won't be merged (read more about this in the "merge strategies" section). + - Ensuring the Signed-off-by-trailer Contributors need to sign the "Contributor License Agreement". They do so by signing off each individual commit with a so-called "Signed-off-by Trailer". -- cgit v1.2.3 From 9ad1c06a2f913a31a614083ac038536ec1acf585 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 22 Jun 2022 14:12:55 +0200 Subject: Add content for "testing" section Signed-off-by: Matthias Beyer --- GOVERNANCE.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 4dec595d..6e96797a 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -162,6 +162,13 @@ core contributors = [SAG, IFM] Coding style is enforced via `rustfmt` in its default configuration. Compliance with the coding style is enforced via CI. - testing + Testing is done via workflows in github actions using `cargo test --all-features` for all + crates. + The main objective with this is that a developer should be able to simply run + `cargo test` on their local machine to be able to see whether CI would succeed + for changes they submit in a pull request. + Thus, all tests (unit tests, but also integration tests) are implemented in + Rust and do not rely on external services. - benchmarks - documentation builds - keeping spec up to date -- cgit v1.2.3 From f1c27bf0fee78fd67a3ef90f646ac86e5c64c841 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Wed, 22 Jun 2022 14:13:09 +0200 Subject: Add content for "documentation builds" section Signed-off-by: Matthias Beyer --- GOVERNANCE.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 6e96797a..3c83a2d2 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -171,6 +171,9 @@ core contributors = [SAG, IFM] Rust and do not rely on external services. - benchmarks - documentation builds + Source code documentation as well as other documentation is tested via github + actions workflows as well, to ensure that a developer is able to build all + relevant documentation on their local machine. - keeping spec up to date - evergreen master The project pursues the "evergreen master" strategy. That means that at every -- cgit v1.2.3 From d320740f5f33330ce5382be9092d6680747c2dc6 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Thu, 23 Jun 2022 08:54:42 +0200 Subject: Add content for "dependency updates" section Signed-off-by: Matthias Beyer --- GOVERNANCE.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 3c83a2d2..f09fdc69 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -225,6 +225,15 @@ core contributors = [SAG, IFM] bors-ng is used to prevent "merge skew" or "semantic merge conflicts" (read more [here](https://bors.tech/essay/2017/02/02/pitch/)). - Dependency updates + Dependencies should be kept in sync over all crates in the project. That means + that different crates of the project should try to use dependencies in the + same versions, but also that dependencies should be harmonized in a way that a + specific problem should not be solved with more than one external library at a + time. + Updates of dependencies is automated via a github bot + ([dependabot](https://github.com/dependabot)). + To ensure harmonization of dependencies, a dedicated team (see "Team + Structure") is responsible for keeping an eye on the list of dependencies. - License linting ## Related -- cgit v1.2.3 From 9a3d6add09eddacceec65a5649d4b85cdfbeb09e Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Thu, 23 Jun 2022 08:57:29 +0200 Subject: Add content for "License linting" section Signed-off-by: Matthias Beyer --- GOVERNANCE.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index f09fdc69..8d1362a1 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -235,6 +235,14 @@ core contributors = [SAG, IFM] To ensure harmonization of dependencies, a dedicated team (see "Team Structure") is responsible for keeping an eye on the list of dependencies. - License linting + License linting describes the act of checking the licenses of dependencies and + whether they meet a certain criteria. + For example, it is not feasible to import an external library that is licensed + as GPL-3.0 in an Apache-2.0 licensed codebase. + Because of this, a github action is installed to lint the licenses of + dependencies. This action runs as a normal lint (see "evergreen master") and + blocks pull requests if dependencies get imported that do not meet a set of + rules agreed upon by the project. ## Related -- cgit v1.2.3 From 8e72cd853fee3f6c71b628c3cdcb4b3dfb9bb7f7 Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Tue, 28 Jun 2022 16:49:45 +0100 Subject: Add content for "end-2-end tests" Signed-off-by: Didier Wenzek --- GOVERNANCE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 8d1362a1..abe64465 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -167,8 +167,10 @@ core contributors = [SAG, IFM] The main objective with this is that a developer should be able to simply run `cargo test` on their local machine to be able to see whether CI would succeed for changes they submit in a pull request. - Thus, all tests (unit tests, but also integration tests) are implemented in + Thus, all CI tests (unit tests, but also integration tests) are implemented in Rust and do not rely on external services. + End-to-end system tests - that depend on external services - are run outside the CI pipeline, + to avoid inconsistent test outcomes because of external issues. - benchmarks - documentation builds Source code documentation as well as other documentation is tested via github -- cgit v1.2.3 From b0a13f09755c0db49a7a66e47aac82e3de39859d Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Tue, 28 Jun 2022 16:55:00 +0100 Subject: Remove note on enforcing resolved comments Signed-off-by: Didier Wenzek --- GOVERNANCE.md | 1 - 1 file changed, 1 deletion(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index abe64465..ef8dcb8b 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -221,7 +221,6 @@ core contributors = [SAG, IFM] * No missing `Signed-off-by` lines (ensured via github action) * No "!fixup"/"!squash" commits in the pull request (ensured via github action) - * Conversations must be resolved (ensured via github setting) Merging itself is implemented via a "merge bot": [bors-ng](https://bors.tech). bors-ng is used to prevent "merge skew" or "semantic merge conflicts" -- cgit v1.2.3 From 1628234a59ef555f845d198e5838eee4d3700c7d Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Fri, 22 Jul 2022 12:29:41 +0200 Subject: Fix spelling and grammar Signed-off-by: Didier Wenzek --- GOVERNANCE.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index ef8dcb8b..98dcc086 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,6 +1,6 @@ # Governance thin-edge.io -This documents servers as a guiding document to ease technical decision making in the project as a whole. +This documents serves as a guiding document to ease technical decision-making in the project as a whole. Some of its goals are: @@ -25,7 +25,7 @@ Changes to the vision need to be done in a plenum of stakeholders, this makes su * Teams are either single contributors or a group of them * They are responsible for a specific part of project, and as such are the maintainers of those parts - * This includes: Reviewing pull requests, triaging issues assigned to them, and general maintenance + * This includes: Reviewing pull requests, triaging issues in their assigned area, and general maintenance * Each team is assigned a single or multiple subtrees of the project, as defined by the project structure * The teams follow the project hierarchy for decisions, i.e. higher decisions take precedence @@ -33,8 +33,8 @@ The important bits: At the top, each invested party has their representative, who together with the others in their group have to come to conclusions together. These should be based on the following factors: -- The signed off vision of the whole project -- Feasability, accounting for future technical and cultural shifts +- The vision of the whole project +- Feasibility, accounting for future technical and cultural shifts - The health of the project going forward Overall, these 'project leads' should not be beholden to their respective companies, and instead to the health of the project and its community. @@ -43,7 +43,7 @@ Underneath the leads are the teams or individuals, that each are allowed to mak - Some decisions are global in the project, like the core/API - - Team members should try and make sure to explore possible options together before calling for a vote. This mostly includes uncontroversial changes that are low impact or have already been agreed upon + - Team members should try to make sure to explore possible options together before calling for a vote. This mostly includes uncontroversial changes that are low impact or have already been agreed upon - If this is not possible, a vote needs to be held: TODO - Some decisions are local, e.g. a plugin does not impact others with its behaviour, however it still needs to be a 'good citizen' in the project (CI, format, etc..) @@ -101,24 +101,24 @@ core contributors = [SAG, IFM] - clear commits - Having clear, consise and well-written commit messages for all changes is not + Having clear, concise and well-written commit messages for all changes is not only a indicator for the seriousness of the project, but also a way to ensure - sustainable development via replicability of the sources of the project. + sustainable development via repeatability of the sources of the project. Because of this, we try to ensure the highest possible quality for each individual commit message. Because such a thing cannot necessarily or in full be enforced via tooling, it - remains mainly the obligation of a reviewer of a changeset to ensure + remains mainly the obligation of a reviewer of a change-set to ensure - * Seclusiveness of the individual commits - * that one commit is one atomic change, and not an accummulation of several - individual and seperate changes + * Exclusiveness of the individual commits + * that one commit is one atomic change, and not an accumulation of several + individual and separate changes * that the commit message of the change expresses why the change was made Every reviewer of a pull request is asked to review not only the changes, but also the commit messages. - Reviewers are explicitely empowered and actually encouraged to block pull + Reviewers are explicitly empowered and actually encouraged to block pull requests that contain commit messages that do not meet a certain standard even and especially also if the proposed changes are acknowledged. @@ -203,7 +203,7 @@ core contributors = [SAG, IFM] job is employed to block pull requests from being merged if such commits are in the PR branch. Rebase should be used to clean those up. - It is explicitely _not_ forbidden to have merge-commits in a pull request. + It is explicitly _not_ forbidden to have merge-commits in a pull request. Long-running pull requests that contain a large number of changes and are developed over a long period might contain merges. They might even merge `master`/`main` to get up-to-date with the latest developments. Though it is -- cgit v1.2.3 From 29d1a98468c30c1a0fa29b78fd6edd9eae3284a3 Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Fri, 22 Jul 2022 13:19:44 +0200 Subject: Make role names clearer Signed-off-by: Didier Wenzek --- GOVERNANCE.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 98dcc086..9d59c3e0 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -31,13 +31,14 @@ Changes to the vision need to be done in a plenum of stakeholders, this makes su The important bits: -At the top, each invested party has their representative, who together with the others in their group have to come to conclusions together. These should be based on the following factors: +At the 'top' are the maintainers, whose job is to define and realize the project vision of thin-edge.io. +Maintainers should strive for agreement based on the following factors: - The vision of the whole project - Feasibility, accounting for future technical and cultural shifts - The health of the project going forward -Overall, these 'project leads' should not be beholden to their respective companies, and instead to the health of the project and its community. +Overall, the maintainers should not be beholden to their respective companies, and instead to the health of the project and its community. Underneath the leads are the teams or individuals, that each are allowed to make similar decisions about the project *in the area they have been delegated*. @@ -56,7 +57,7 @@ Underneath the leads are the teams or individuals, that each are allowed to mak The project has a hierarchy to solve these two problems: -1. How can participating organizations make sure that their voice and interests are represented in the project? +1. How can users make sure that their voice and interests are represented in the project? - Each member party appoints one core team member - They form the group of people that have to, and are responsible for, signing off on the technical implementation of the project 2. How to make the lives of these team members easier? -- cgit v1.2.3 From 127eaa1119cd04e8ea00e5d9342848fdf792593a Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Fri, 22 Jul 2022 13:24:02 +0200 Subject: Fix style Signed-off-by: Didier Wenzek --- GOVERNANCE.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 9d59c3e0..65a6e4bc 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -101,7 +101,7 @@ core contributors = [SAG, IFM] ## Repository maintenance -- clear commits +- **Clear commits** Having clear, concise and well-written commit messages for all changes is not only a indicator for the seriousness of the project, but also a way to ensure sustainable development via repeatability of the sources of the project. @@ -147,7 +147,7 @@ core contributors = [SAG, IFM] Commits using the `--fixup` or `--squash` feature of `git-commit` are allowed, but won't be merged (read more about this in the "merge strategies" section). -- Ensuring the Signed-off-by-trailer +- **Ensuring the Signed-off-by-trailer** Contributors need to sign the "Contributor License Agreement". They do so by signing off each individual commit with a so-called "Signed-off-by Trailer". Git offers the `--signoff`/`-s` flags when using `git-commit` to commit @@ -159,10 +159,10 @@ core contributors = [SAG, IFM] request misses the `Signed-off-by` trailer. As a result, it is not possible to merge pull requests that miss the trailer. -- coding styleguide +- **Coding styleguide** Coding style is enforced via `rustfmt` in its default configuration. Compliance with the coding style is enforced via CI. -- testing +- **Testing** Testing is done via workflows in github actions using `cargo test --all-features` for all crates. The main objective with this is that a developer should be able to simply run @@ -172,20 +172,20 @@ core contributors = [SAG, IFM] Rust and do not rely on external services. End-to-end system tests - that depend on external services - are run outside the CI pipeline, to avoid inconsistent test outcomes because of external issues. -- benchmarks -- documentation builds +- **Benchmarks** +- **Documentation builds** Source code documentation as well as other documentation is tested via github actions workflows as well, to ensure that a developer is able to build all relevant documentation on their local machine. -- keeping spec up to date -- evergreen master +- **Keeping spec up to date** +- **Evergreen master** The project pursues the "evergreen master" strategy. That means that at every point in time, the commit that `master`/`main` points to must successfully build and pass all tests successfully. Reaching that goal is possible because of the employed merge strategies (read below). -- merge strategies +- **Merge strategies** Merging is the way how the project accepts and implements changes. Because of the pursued "everygreen master", merging is implemented in a @@ -226,7 +226,7 @@ core contributors = [SAG, IFM] Merging itself is implemented via a "merge bot": [bors-ng](https://bors.tech). bors-ng is used to prevent "merge skew" or "semantic merge conflicts" (read more [here](https://bors.tech/essay/2017/02/02/pitch/)). -- Dependency updates +- **Dependency updates** Dependencies should be kept in sync over all crates in the project. That means that different crates of the project should try to use dependencies in the same versions, but also that dependencies should be harmonized in a way that a @@ -236,7 +236,7 @@ core contributors = [SAG, IFM] ([dependabot](https://github.com/dependabot)). To ensure harmonization of dependencies, a dedicated team (see "Team Structure") is responsible for keeping an eye on the list of dependencies. -- License linting +- **License linting** License linting describes the act of checking the licenses of dependencies and whether they meet a certain criteria. For example, it is not feasible to import an external library that is licensed -- cgit v1.2.3 From 95a18774959e8ae1bc9bbf024d3fd201752206cf Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Fri, 22 Jul 2022 13:30:52 +0200 Subject: Improve wording making statements stronger Signed-off-by: Didier Wenzek --- GOVERNANCE.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 65a6e4bc..b0f5bfc2 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -44,8 +44,8 @@ Underneath the leads are the teams or individuals, that each are allowed to mak - Some decisions are global in the project, like the core/API - - Team members should try to make sure to explore possible options together before calling for a vote. This mostly includes uncontroversial changes that are low impact or have already been agreed upon - - If this is not possible, a vote needs to be held: TODO + - Team members should try to make sure to explore possible options together before calling for time-consuming solutions like a vote. This mostly includes uncontroversial changes that are low impact or have already been agreed upon + - If an exclusive choice has to be made (where it is not possible to entertain two conflicting approaches), and no clear side is more advantageous to pick, a vote should be held with the majority opinion being the final decision. - Some decisions are local, e.g. a plugin does not impact others with its behaviour, however it still needs to be a 'good citizen' in the project (CI, format, etc..) - These should be clearly scoped in their respective project part @@ -69,7 +69,7 @@ The project has a hierarchy to solve these two problems: * The sub-projects are organized in a hierarchy * This makes it easier to decouple different parts of the project * This makes it easier to decide on technical questions - * Everyone has to agree on the core project bringing the foundations to all others. + * Everyone has to agree on the core project as it is the foundations to all others. * At the periphery, sub-projects might be related to specific eco-systems (e.g. Cumulocity or Moneo) and therefore have independent decision processes. * At an intermediate level, one might have sub-projects related to specific use-cases like “JSON over MQTT”. * All the sub-projects share a common repository - to ease consistency across projects and over time. @@ -100,6 +100,7 @@ core contributors = [SAG, IFM] ## Repository maintenance +To assure a consistent level of quality and appearance, the project has some rules for maintainers to follow: - **Clear commits** Having clear, concise and well-written commit messages for all changes is not -- cgit v1.2.3 From 8c49ea054f8556550cd44b7169e0b407af85f4b2 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Mon, 25 Jul 2022 19:17:12 +0200 Subject: Add chapter on release workflow Co-authored-by: Rina Fujino Signed-off-by: Rina Fujino Signed-off-by: Matthias Beyer --- GOVERNANCE.md | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 204 insertions(+) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index b0f5bfc2..32a14ff8 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -247,6 +247,210 @@ To assure a consistent level of quality and appearance, the project has some rul blocks pull requests if dependencies get imported that do not meet a set of rules agreed upon by the project. +## Release workflow + +The following describes how thin-edge.io is released. + +The following chapters do not talk about major releases (increasing "x" in a +"x.y.z" version number) as there is no workflow for these implemented yet. + + +### Preface + +The following chapter describes the release process of the thin-edge.io project +and the corrosponding crates. + +The goal of the workflow described in this chapter is to have _as little impact +as possible_ on the general development of the project. +Releases should _never_ stop, prevent or even just slow down the normal +development of the project. +For example, halting development on the `main` branch and forbidding +contributors and maintainers to merge changes to it even for as little as one +hour just so that a new release can be published is not acceptable. +Also should "patch" releases (sometimes called "bugfix releases") have no impact +on the project pace or even concern developers - they should just happen in +parallel without any influence on the normal development activities. + +With these requirements, we implement the following workflow. + +### Semver conformity and API coverage + +We adhere to [semver](https://semver.org), +with the [exceptions implied by the cargo implementation of the standard](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-cratesio). + +Parts of the API that are covered by semver are explicitly marked. Our public +API is extensively tested in integration tests. If changes to the public API of +thin-egde.io are necessary, these changes are documented in the `CHANGELOG.md` +file of the project, with reasoning why the change was necessary and how users +can upgrade to the new interface(s). + + + +We also define the following rules for our release process: + +* We release new features by increasing the "minor" version +* When we release new patch releases, these releases never contain new features, + but only fixes to bugs. + +### Release cycle + +Minor releases are published roughly every TBD months. + +Until a minor release is published, the previous minor release _can_ receive +patch releases (accordingly to [semver](https://semver.org/)). + +### Strategy + +We use the release-branch strategy, where development happens on the `main` +branch and releases are done on dedicated `release-X.Y.Z` branches. + +Because we employ the "evergreen main branch" strategy and all of our merge +commits on the `main` branch are guaranteed to successfully build and pass CI, a +release can potentially be made starting from every commit on the `main` branch. + +For a description of the release workflow, read below. + +### Release maintainer + +For every release, one or more "release maintainers" are appointed by the core team. + +The responsibilities of the release maintainers are: + +* Creation and maintenance of the `release-x.y.z` branches +* Cherry-picking bugfix patches from the `main` branch and applying them to the + relevant `release-x.y.z` branch (via pull request to that branch) + * If a patch does not apply cleanly, it is _not_ the responsibility of the + release maintainer to make the patch apply. It is responsibility of the + release maintainer, though, to talk to the developer of the patch and work + with them to port the fix back to the release +* Create git-tags for the release(s) as appropriate +* Create github artifacts (or take care of a github-action pipeline that does) + for releases +* Port the changes to the `CHANGELOG.md` file back to `main` (via pull request) +* Submit pull requests to the `main` branch to update all version numbers for + the next release cycle + +It is explicitely allowed for everyone to open bugfix-backport pull requests to +a release branch, but the release maintainer(s) decide when and how to apply +them to the release branch. + +### Release branches + +Release branches MUST be named with a pattern. This pattern is + +``` +"release" dash dot dot "x" +``` + +The `"x"` is used instead of the "patch version number", because patch releases +are published from the release branches (read below). + +A release branch gets the following rules enforced via GitHub: + +* Only the "release-maintainers" team can create branches named `"release-*"` +* Pull requests are required on these branches +* Status checks are required to succeed on these branches +* "CODEOWNERS" is **not** enforced on these branches +* These rules are also enforced for administrators + +### Workflow for minor releases + +The following steps happen when a minor release is made: + +1. One release maintainer creates a branch, starting from a recent commit on + `main`, named after the aforementioned naming rule. +2. It is ensured that this branch cannot be pushed to by anyone except the + [bors merge bot](https://bors.tech) + (Refer to the "Merge strategies" point in the "Repository maintenance" + chapter for more information) +3. The release maintainer crafts the `CHANGELOG.md` entries for this release and + opens a pull request for it, targeting the aforementioned release branch. +4. Once agreed upon with everyone involved, they merge the PR for the + `CHANGELOG.md` to the release branch +5. The release maintainer publishes the release on crates.io and creates a new + tag for the release. + They might add a tag message as they seem appropriate. + They then push the tag to the GitHub repository of the project. + They also make sure that release artifacts are published on GitHub for the + new release (or make sure that a github-actions pipeline does this) +6. After the release is done, the `CHANGELOG.md` changes are cherry-picked to a + pull request to the `main` branch by the release maintainer +7. After the release is done, the release maintainer opens a pull request to the + `main` branch to update all version numbers of all crates to the next minor + version + +### Workflow for patch releases + +Patch releases are published when appropriate, there is no fixed release cycle. +It might be a good rule-of-thumb to not release more than one patch release per +week. + +#### Backporting + +Bugfixes that are added to a patch release _must_ have been applied to the +`main` branch, before they are backported to the appropriate `release-x.y.z` +branch. +If a bugfix that is applied to `main` cannot be backported, due to either +conflicts or because the feature that is about to be fixed does not exist in the +`release-x.y.z` branch anymore, the patch may be adapted to apply cleanly or a +special patch may be crafted. +The release maintainer is encouraged to reach out to the developer of the patch, +as it is _not_ the responsibility of the release maintainer to adapt patches. + +In any case, fixes that are backported to a `release-x.y.z` branch, MUST pass +CI and thus MUST be submitted to the release branch via a pull request. + +#### Publishing of patch releases + +A patch release is published as soon as the release maintainer thinks it is +appropriate. + +The steps the release maintainer follows are almost the same as the steps of the +minor release workflow: + +* The release maintainer submits a pull request to the release branch with the + following changes: + * `CHANEGLOG.md` entries for the patch level release + * Updates of the version numbers for all crates in the "patch"-level position, + e.g. "0.42.0" becomes "0.42.1", +* Once the aforementioned pull request is merged, the release maintainer + publishes the release on crates.io, tags (`git tag -a vMAJOR.MINOR.PATCH`) + the release and pushes the tag to the GitHub repository of the project +* Once the release is published, the release maintainer opens a pull request to + the `main` branch of the project, porting the changes that were made to the + `CHANGELOG.md` file to this branch + +### More + +The `CHANGELOG.md` is added on the release branch rather than on the `main` +branch. The reason for this is the workflow: If the changelog is adapted on +`main`, the branchoff for the release branch can _only_ happen directly after +the changelog was merged, because other merges may introduce new changes that +need to be in the changelog. Also, the changelog-adding pull request must be up +to date all the time, if patches get merged to `main` _while_ the changelog is +written, the changelog would need further fixes. +If the changelog is added on the release branch, no synchronization is +necessary, as the branchoff for the release already happened. +Instead, the changelog entries can be "backported" to `main`, which is trivial. + +In a similar fashion are patch-level `CHANGELOG.md` entries ported to the `main` +branch. + +Version number bumps happen right _after_ branchoff for a release. Doing the +version number bump before the release would mean that the release maintainers +would have to wait for the version-bump-pull-request, which is not acceptable +under the preassumption that every commit from `main` can potentially be +released. +By bumping the numbers right _after_ the release, but for the next release, we +automatically get a peace-of-mind state for that next release, where the release +maintainers can again just take any commit on `main` and start their release +process. + +The implication of the patch-level release workflow is that the `main` branch +does never see changes to the version strings of the crates in the "patch" level +position. This is intentional, as there is no need for that. + + ## Related * [Understanding open source governance models](https://www.redhat.com/en/blog/understanding-open-source-governance-models) -- cgit v1.2.3 From cf039bbbc40d71d9b5938e84af3bdb5cf648d747 Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Fri, 19 Aug 2022 16:21:48 +0200 Subject: Make wording more consistent Signed-off-by: Didier Wenzek --- GOVERNANCE.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 32a14ff8..647ff610 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -38,9 +38,10 @@ Maintainers should strive for agreement based on the following factors: - Feasibility, accounting for future technical and cultural shifts - The health of the project going forward -Overall, the maintainers should not be beholden to their respective companies, and instead to the health of the project and its community. +The maintainers ensure that all changes in the project align with the agreed vision +and support the health of the project and its community without being unduly influenced from their employers. -Underneath the leads are the teams or individuals, that each are allowed to make similar decisions about the project *in the area they have been delegated*. +Underneath the maintainers are the teams or individuals, that each are allowed to make similar decisions about the project *in the area they have been delegated*. - Some decisions are global in the project, like the core/API @@ -100,12 +101,12 @@ core contributors = [SAG, IFM] ## Repository maintenance -To assure a consistent level of quality and appearance, the project has some rules for maintainers to follow: +To assure a consistent level of quality and appearance, the project has some rules for contributors to follow: - **Clear commits** Having clear, concise and well-written commit messages for all changes is not only a indicator for the seriousness of the project, but also a way to ensure - sustainable development via repeatability of the sources of the project. + sustainable development via replicability of the sources of the project. Because of this, we try to ensure the highest possible quality for each individual commit message. @@ -113,7 +114,7 @@ To assure a consistent level of quality and appearance, the project has some rul Because such a thing cannot necessarily or in full be enforced via tooling, it remains mainly the obligation of a reviewer of a change-set to ensure - * Exclusiveness of the individual commits + * Atomicity of the individual commits * that one commit is one atomic change, and not an accumulation of several individual and separate changes * that the commit message of the change expresses why the change was made @@ -182,7 +183,7 @@ To assure a consistent level of quality and appearance, the project has some rul - **Evergreen master** The project pursues the "evergreen master" strategy. That means that at every point in time, the commit that `master`/`main` points to must successfully - build and pass all tests successfully. + build and pass all tests. Reaching that goal is possible because of the employed merge strategies (read below). @@ -197,13 +198,14 @@ To assure a consistent level of quality and appearance, the project has some rul The following actions are **not** allowed: - * Committing to `master`/`main` directly + * Committing to `master`/`main` directly. + The GitHub repository is configured to block pushing to `master`/`main`. * Squash-Merging of pull requests (which is equivalent to committing to `master`/`main` directly). The github repository is configured to not allow squash merges. - * Merging of "!fixup" or "!squash" commits. A github actions + * Merging of "fixup!" or "squash!" commits. A github actions job is employed to block pull requests from being merged if such commits are - in the PR branch. Rebase should be used to clean those up. + in the branch of the pull request. Rebase should be used to clean those up. It is explicitly _not_ forbidden to have merge-commits in a pull request. Long-running pull requests that contain a large number of changes and are @@ -221,7 +223,7 @@ To assure a consistent level of quality and appearance, the project has some rul * builds, tests, lints are green (ensured via github action) * Commit linting (ensured via github action) * No missing `Signed-off-by` lines (ensured via github action) - * No "!fixup"/"!squash" commits in the pull request (ensured via github + * No "fixup!"/"squash!" commits in the pull request (ensured via github action) Merging itself is implemented via a "merge bot": [bors-ng](https://bors.tech). @@ -245,7 +247,7 @@ To assure a consistent level of quality and appearance, the project has some rul Because of this, a github action is installed to lint the licenses of dependencies. This action runs as a normal lint (see "evergreen master") and blocks pull requests if dependencies get imported that do not meet a set of - rules agreed upon by the project. + rules agreed upon by the project maintainers. ## Release workflow -- cgit v1.2.3