first draft of tenets #14
Conversation
|
We can always add more as we think about them. I'm also putting them here as a way of stating that "we hold these to be true for ALL of our repos, not just this one". |
… for writing down requirements
|
|
||
| 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 judgment to be applied, |
There was a problem hiding this comment.
Some teams might, under time pressure, be willing to take calculated risks and might ask for andon cord type exceptions to machine enforceable rules. Maybe some kind of call-out that Intermittent human over-rides mean the rule also needs refinement and review.
There was a problem hiding this comment.
I like the idea of "if the cord gets pulled on the same rule with frequency greater than X". I'm going to think on how/where best to incorporate that, but that'll be a subject for future PRs I think.
| or a situation is too ambiguous for the automation to understand. | ||
|
|
||
| When a situation passes a defined ambiguity threshold | ||
| our automation MUST halt and request human intervention. |
There was a problem hiding this comment.
Ok, this sort of addresses my previous comment.
| ## What this document is | ||
|
|
||
| The purpose of this document is to define our tenets and goals | ||
| for how we will manage our repositories. |
There was a problem hiding this comment.
These tenets & goals apply equally to private/internal and public/external repositories?
There was a problem hiding this comment.
Yes.
The extent to which we can apply them to different scopes and locations is an implementation detail and out of scope for this document (ex: GitHub Actions doesn't work on private repos yet.)
| 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. | ||
|
|
There was a problem hiding this comment.
Is the the correct location to also mention that having written requirements also makes it easier to plan and track progress against the requirements?
There was a problem hiding this comment.
Yes, absolutely! :) I'll add that in.
|
|
||
| #### Enforced Rules | ||
|
|
||
| All requirements SHOULD be machine enforced. |
There was a problem hiding this comment.
How does this jive with line 57 where we state that all requirements MUST be machine enforceable?
There was a problem hiding this comment.
Target vs reality. Requirements MUST be machine enforceable, but only SHOULD be machine enforced. The goal is that everything will be machine enforced, but the reality is that as we get started and as we add further requirements, there will be a period of time when humans need to enforce them.
Subsequent docs will delve into what our requirements are and how we plan to enforce them.
| Any preferences that can be machine enforced | ||
| SHOULD be machine enforced, | ||
| and SHOULD then be made into requirements. |
There was a problem hiding this comment.
Why not have preferences that can be machine enforced MUST be required to be machine enforced but SHOULD become requirements? It would mean that any preferences are permanently fixed until a change is needed and are easy to replicate in other projects.
If we didn't want to make the suggested change I would like to change the text so that it encourages users to machine enforce as much as they can.
There was a problem hiding this comment.
I would actually be inclined to go the other direction:
If a preference can be machine enforced, it MUST become a requirement.
All requirements SHOULD be machine enforced.
See previous comment for why ^ is not MUST.
Description of changes:
As we start formalizing and documenting how we want to automate our repository management, we first need to define what we are attempting to accomplish.
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.