From a95256100e2d61cd009588af197786981f93b0a0 Mon Sep 17 00:00:00 2001 From: mattsb42-aws Date: Wed, 29 Jan 2020 16:37:49 -0800 Subject: [PATCH 1/9] add first draft of tenets --- repo-management/tenets.md | 86 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 repo-management/tenets.md diff --git a/repo-management/tenets.md b/repo-management/tenets.md new file mode 100644 index 0000000..1b098c1 --- /dev/null +++ b/repo-management/tenets.md @@ -0,0 +1,86 @@ +# Repository Management Tenets and Goals + +## Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL +NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and +"OPTIONAL" in this document are to be interpreted as described in +[RFC 2119](https://tools.ietf.org/html/rfc2119). + +## What this document is + +The purpose of this document is to define our tenets and goals +for how we will manage our repositories. +This will serve as the point of reference for all other documents +that discuss how to achieve those goals. + +## What this document is not + +This document does *not* discuss how we will achieve any of these goals. + + +## Tenets + +1. [Mechanisms, not good intentions.](#Mechanisms) +1. [If it's not written down, it doesn't exist.](#Written Rules) +1. [Rules must be machine-enforceable.](#Enforceable Rules) +1. [Minimal human involvement.](#Human Involvement) +1. [Simple human intervention.](#Human Intervention) + + +### Mechanisms + +If we care about something happening, +it MUST NOT be dependent on the good intentions of humans. +It MUST be enforceable without direct human action. + +### Written Rules + +If we care about managing something about a repository, +we MUST write that thing down. +Unwritten rules cannot be enforced by mechanisms. + +This is important for two reasons: + +1. We must be able to efficiently communicate our requirements to all maintainers. + The only way that we can do this reliably is by writing them down. +1. Maintainers understanding our requirements is necessary but not sufficient. + We must also communicate those requirements to our users and contributors. + The only way that we can do this reliably is by writing them down. + +### Enforceable Rules + +Any rules that we define MUST be machine enforceable. +If a machine cannot enforce a rule then that rule is not sufficiently well defined. + +For a rule to be enforceable, it MUST NOT be ambiguous. + +For example, if we want to require that unit tests complete +then we MUST define branch protection rules that enforce that requirement. + +This is important for two reasons: + +1. If we have not defined our requirements well enough for a machine to enforce them, + then we have not defined them well enough for all humans to understand them. +1. If a rule requires human judgement to be applied, + then that rule is incomplete. + +Ambiguity in life is unavoidable, but ambiguity MUST be the exception. + +For example, it is reasonable to have a rule that states clearly when a human must be engaged, +but it is not reasonable to have a rule that states that a human must always be engaged +in order to determine + +### Human Involvement + +Humans should not need to engage with automation unless something has gone wrong +or a situation is sufficiently ambiguous to go beyond the known rules. + +When a situation does pass a defined ambiguity threshold, +our automation MUST automatically halt and request human intervention. + +### Human Intervention + +Anyone with write access to a repository MUST be able to stop any automation +if they think something has gone wrong or will go wrong +or if they think that a situation is sufficiently ambiguous. From 73924f4f024513539ab728376eea40551f4991e3 Mon Sep 17 00:00:00 2001 From: mattsb42-aws Date: Thu, 30 Jan 2020 16:22:11 -0800 Subject: [PATCH 2/9] clarify some language --- repo-management/tenets.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/repo-management/tenets.md b/repo-management/tenets.md index 1b098c1..e192b1b 100644 --- a/repo-management/tenets.md +++ b/repo-management/tenets.md @@ -7,6 +7,8 @@ NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). + + ## What this document is The purpose of this document is to define our tenets and goals @@ -67,16 +69,16 @@ This is important for two reasons: Ambiguity in life is unavoidable, but ambiguity MUST be the exception. -For example, it is reasonable to have a rule that states clearly when a human must be engaged, +For example, it is reasonable to have a rule that states clearly when a human must be engaged but it is not reasonable to have a rule that states that a human must always be engaged -in order to determine +in order to determine whether a human must be engaged. ### Human Involvement -Humans should not need to engage with automation unless something has gone wrong +Humans SHOULD NOT need to engage with automation unless something has gone wrong or a situation is sufficiently ambiguous to go beyond the known rules. -When a situation does pass a defined ambiguity threshold, +When a situation passes a defined ambiguity threshold our automation MUST automatically halt and request human intervention. ### Human Intervention From daafcf2e63e0f0b29add5798ddfe390e5bc6adbb Mon Sep 17 00:00:00 2001 From: mattsb42-aws Date: Thu, 30 Jan 2020 16:45:00 -0800 Subject: [PATCH 3/9] clarify human intervention --- repo-management/tenets.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/repo-management/tenets.md b/repo-management/tenets.md index e192b1b..e6e2aa9 100644 --- a/repo-management/tenets.md +++ b/repo-management/tenets.md @@ -7,8 +7,6 @@ NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). - - ## What this document is The purpose of this document is to define our tenets and goals @@ -84,5 +82,5 @@ our automation MUST automatically halt and request human intervention. ### Human Intervention Anyone with write access to a repository MUST be able to stop any automation -if they think something has gone wrong or will go wrong -or if they think that a situation is sufficiently ambiguous. +if they think something has gone wrong, will go wrong, +or that a situation is sufficiently ambiguous. From 8daae908ce80adacff6b32c088823daae53fc8bd Mon Sep 17 00:00:00 2001 From: mattsb42-aws Date: Mon, 3 Feb 2020 18:25:49 -0800 Subject: [PATCH 4/9] clarify requirements vs preferences --- repo-management/tenets.md | 50 +++++++++++++++++++++++++-------------- 1 file changed, 32 insertions(+), 18 deletions(-) diff --git a/repo-management/tenets.md b/repo-management/tenets.md index e6e2aa9..03b12bf 100644 --- a/repo-management/tenets.md +++ b/repo-management/tenets.md @@ -1,12 +1,5 @@ # Repository Management Tenets and Goals -## Definitions - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL -NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and -"OPTIONAL" in this document are to be interpreted as described in -[RFC 2119](https://tools.ietf.org/html/rfc2119). - ## What this document is The purpose of this document is to define our tenets and goals @@ -17,7 +10,20 @@ that discuss how to achieve those goals. ## What this document is not This document does *not* discuss how we will achieve any of these goals. +Implementation requirements and approaches are discussed in other documents. +## Definitions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL +NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and +"OPTIONAL" in this document are to be interpreted as described in +[RFC 2119](https://tools.ietf.org/html/rfc2119). + +* **Requirement** : A requirement is something that MUST be true. + An example of this could be that secrets MUST NOT be committed in code. +* **Preference** : A preference is something that SHOULD be true, + but that we will not force to be true. + An example of this could be design patterns or ## Tenets @@ -30,15 +36,12 @@ This document does *not* discuss how we will achieve any of these goals. ### Mechanisms -If we care about something happening, -it MUST NOT be dependent on the good intentions of humans. -It MUST be enforceable without direct human action. +Requirements MUST NOT be dependent on the good intentions of humans. +They MUST be enforceable without direct human action. ### Written Rules -If we care about managing something about a repository, -we MUST write that thing down. -Unwritten rules cannot be enforced by mechanisms. +Requirements MUST be defined in written documentation. This is important for two reasons: @@ -47,16 +50,19 @@ This is important for two reasons: 1. Maintainers understanding our requirements is necessary but not sufficient. We must also communicate those requirements to our users and contributors. The only way that we can do this reliably is by writing them down. +1. We cannot enforce undefined requirements. ### Enforceable Rules -Any rules that we define MUST be machine enforceable. -If a machine cannot enforce a rule then that rule is not sufficiently well defined. +All requirements MUST be machine enforceable. +If a machine cannot enforce a requirement +then that requirement is not sufficiently well defined. -For a rule to be enforceable, it MUST NOT be ambiguous. +For a requirement to be enforceable, it MUST NOT be ambiguous. -For example, if we want to require that unit tests complete -then we MUST define branch protection rules that enforce that requirement. +For example, if we want to require that unit tests pass, +we can enforce that by defining branch protection rules +that will block a merge if the unit tests have not passed. This is important for two reasons: @@ -71,6 +77,14 @@ For example, it is reasonable to have a rule that states clearly when a human mu but it is not reasonable to have a rule that states that a human must always be engaged in order to determine whether a human must be engaged. +#### Enforced Rules + +All requirements SHOULD be machine enforced. + +Any preferences that can be machine enforced +SHOULD be machine enforced, +and SHOULD then be made into requirements. + ### Human Involvement Humans SHOULD NOT need to engage with automation unless something has gone wrong From ece5413d92134c69ff5bfe3441a731968e635cb8 Mon Sep 17 00:00:00 2001 From: mattsb42-aws Date: Mon, 3 Feb 2020 18:32:51 -0800 Subject: [PATCH 5/9] add consistency tenet --- repo-management/tenets.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/repo-management/tenets.md b/repo-management/tenets.md index 03b12bf..585d64b 100644 --- a/repo-management/tenets.md +++ b/repo-management/tenets.md @@ -32,7 +32,7 @@ NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and 1. [Rules must be machine-enforceable.](#Enforceable Rules) 1. [Minimal human involvement.](#Human Involvement) 1. [Simple human intervention.](#Human Intervention) - +1. [Be Consistent](#Consistency) ### Mechanisms @@ -98,3 +98,17 @@ our automation MUST automatically halt and request human intervention. Anyone with write access to a repository MUST be able to stop any automation if they think something has gone wrong, will go wrong, or that a situation is sufficiently ambiguous. + +### Consistency + +> Special cases aren't special enough to break the rules. +> +> -- The Zen of Python + +Requirements and preferences SHOULD be consistent with relevant community norms. +Where they diverge, that divergence MUST be to raise the bar +and the reasons for that divergence MUST be clearly documented. + +Requirements and preferences MUST be consistent across projects +governed by this document that share common characteristics +(ex: language, build system, etc). From 3756933abc4038797317f6d572ff3c0bca50dc3b Mon Sep 17 00:00:00 2001 From: mattsb42-aws Date: Tue, 4 Feb 2020 12:42:13 -0800 Subject: [PATCH 6/9] address comments --- repo-management/tenets.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/repo-management/tenets.md b/repo-management/tenets.md index 585d64b..a038871 100644 --- a/repo-management/tenets.md +++ b/repo-management/tenets.md @@ -45,11 +45,10 @@ Requirements MUST be defined in written documentation. This is important for two reasons: -1. We must be able to efficiently communicate our requirements to all maintainers. - The only way that we can do this reliably is by writing them down. -1. Maintainers understanding our requirements is necessary but not sufficient. - We must also communicate those requirements to our users and contributors. - The only way that we can do this reliably is by writing them down. +1. We MUST efficiently communicate our requirements to all maintainers. + The only way that we can do this is by writing them down. +1. We MUST communicate our requirements to our users and contributors. + The only way that we can do this is by writing them down. 1. We cannot enforce undefined requirements. ### Enforceable Rules @@ -73,9 +72,8 @@ This is important for two reasons: Ambiguity in life is unavoidable, but ambiguity MUST be the exception. -For example, it is reasonable to have a rule that states clearly when a human must be engaged -but it is not reasonable to have a rule that states that a human must always be engaged -in order to determine whether a human must be engaged. +For example, it is reasonable to have a rule that states clearly when a human MUST be engaged +but it is not reasonable to have a rule that states that a human MUST always be engaged. #### Enforced Rules @@ -88,10 +86,10 @@ and SHOULD then be made into requirements. ### Human Involvement Humans SHOULD NOT need to engage with automation unless something has gone wrong -or a situation is sufficiently ambiguous to go beyond the known rules. +or a situation is too ambiguous for the automation to understand. When a situation passes a defined ambiguity threshold -our automation MUST automatically halt and request human intervention. +our automation MUST halt and request human intervention. ### Human Intervention From c6709de8009127cefc7bb9afc4254bb25c860ed6 Mon Sep 17 00:00:00 2001 From: mattsb42-aws Date: Wed, 5 Feb 2020 10:50:23 -0800 Subject: [PATCH 7/9] spelling and grammar --- repo-management/tenets.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/repo-management/tenets.md b/repo-management/tenets.md index a038871..8880b47 100644 --- a/repo-management/tenets.md +++ b/repo-management/tenets.md @@ -36,7 +36,7 @@ NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and ### Mechanisms -Requirements MUST NOT be dependent on the good intentions of humans. +Requirements MUST NOT depend on the good intentions of humans. They MUST be enforceable without direct human action. ### Written Rules @@ -67,7 +67,7 @@ This is important for two reasons: 1. If we have not defined our requirements well enough for a machine to enforce them, then we have not defined them well enough for all humans to understand them. -1. If a rule requires human judgement to be applied, +1. If a rule requires human judgment to be applied, then that rule is incomplete. Ambiguity in life is unavoidable, but ambiguity MUST be the exception. From ec9ab15a0f994fde2bc171edd33079be2d219853 Mon Sep 17 00:00:00 2001 From: mattsb42-aws Date: Wed, 5 Feb 2020 15:58:59 -0800 Subject: [PATCH 8/9] finish thoughts --- repo-management/tenets.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/repo-management/tenets.md b/repo-management/tenets.md index 8880b47..24905d0 100644 --- a/repo-management/tenets.md +++ b/repo-management/tenets.md @@ -23,7 +23,7 @@ NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and An example of this could be that secrets MUST NOT be committed in code. * **Preference** : A preference is something that SHOULD be true, but that we will not force to be true. - An example of this could be design patterns or + An example of this could be design patterns or code formatting. ## Tenets @@ -32,7 +32,7 @@ NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and 1. [Rules must be machine-enforceable.](#Enforceable Rules) 1. [Minimal human involvement.](#Human Involvement) 1. [Simple human intervention.](#Human Intervention) -1. [Be Consistent](#Consistency) +1. [Be Consistent.](#Consistency) ### Mechanisms From 459bf4c3a88b185a58a4e00bba16a6dccb8af4b0 Mon Sep 17 00:00:00 2001 From: mattsb42-aws Date: Thu, 6 Feb 2020 11:22:30 -0800 Subject: [PATCH 9/9] remove count-dependent framing and add "what if things change" reason for writing down requirements --- repo-management/tenets.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/repo-management/tenets.md b/repo-management/tenets.md index 24905d0..4c2d43a 100644 --- a/repo-management/tenets.md +++ b/repo-management/tenets.md @@ -43,13 +43,14 @@ They MUST be enforceable without direct human action. Requirements MUST be defined in written documentation. -This is important for two reasons: +This is important because: 1. We MUST efficiently communicate our requirements to all maintainers. The only way that we can do this is by writing them down. 1. We MUST communicate our requirements to our users and contributors. The only way that we can do this is by writing them down. 1. We cannot enforce undefined requirements. +1. We cannot know when/if/how requirements change if they are not recorded. ### Enforceable Rules @@ -63,7 +64,7 @@ For example, if we want to require that unit tests pass, we can enforce that by defining branch protection rules that will block a merge if the unit tests have not passed. -This is important for two reasons: +This is important because: 1. If we have not defined our requirements well enough for a machine to enforce them, then we have not defined them well enough for all humans to understand them.