Skip to content

policy: add policy on policies - #60

Open
dsmk wants to merge 6 commits into
CCI-MOC:mainfrom
dsmk:feat/policy-policy
Open

dsmk wants to merge 6 commits into
CCI-MOC:mainfrom
dsmk:feat/policy-policy

Conversation

@dsmk

@dsmk dsmk commented Nov 19, 2026

Copy link
Copy Markdown

Adopts a Policy on Policies: what counts as a policy in this repository, what a
policy document must contain, and how one is proposed, approved, amended, and
retired.

This is the first pull request to follow the process it defines, so it is also
the bootstrap: please read it as the rule you will be held to, not just as a
document. It needs an approval from each of MOC, BU, and Red Hat, and stays
open at least ten business days from the announcement so that people who are
not approvers can comment.

What's here

  • policies/2026-10-30-policy-on-policies/README.md — the policy.
  • policies/2026-10-30-policy-on-policies/approvers/ — a supporting
    document listing the designated approver and alternate for each institution,
    and the teams that may be named as a policy's responsible-team. Entries are
    TBD; see "Before this can merge" below.
  • README.md — a new "Approving a policy" section summarising the process
    for people working through a PR. It states that the policy governs where the
    two differ, so that editing the README cannot quietly change the approval
    rules.
  • templates/policy/ — rebuilt so that copying it produces a conforming
    policy. The previous template was a two-line stub.

The decisions worth your attention

These are the normative choices. Everything else follows from them.

  1. All three institutions must approve. No majority, no waiver, no
    substitution. Any one institution can block indefinitely.
  2. Five business days minimum. A substantive change to normative text
    restarts the clock; an editorial correction does not.
  3. Two tiers of content. Purpose, Scope, Policy, Exceptions, and Appendices
    are normative and need the full process. Supporting Documents and Related
    Policies are supporting content, which the responsible team can change with
    the usual two reviews. The intent is that facts changing on someone else's
    schedule — supported OS releases, who holds a role — live in supporting
    documents so that routine reality does not require a policy amendment.
  4. Policies are amended in place. The directory name and its date record
    when the policy was first proposed and never change, so published URLs stay
    valid across revisions. Retired policies stay in place rather than being
    deleted.
  5. No approval date in frontmatter. A policy's last-approved date is the
    date of the most recent Normative row of its Version History. One place to
    update, no second copy to drift.
  6. Changing an institution's approver requires that institution's own
    approver.
    The approvers list is supporting content, so without this
    carve-out one institution could change another's representative.
  7. An editorial path exists — typos, formatting, broken links — merging on
    a single approval from any institution, with a PR labelled editorial. Any
    approver can object that a change labelled editorial is substantive, which
    returns it to the full process.

Before this can merge

  • Each institution names its designated approver and alternate, and the
    approvers/ table is filled in. Replying in this thread is enough.
  • Announced to all three institutions, with the date noted here so the ten
    business days can be counted.

dsmk and others added 4 commits November 19, 2026 03:25
Adds the Policy on Policies, which defines what a policy is in this
repository, what a policy document must contain, and how one is proposed,
approved, amended, and retired.

Supporting material and repository changes that go with it:

- policies/2026-10-30-policy-on-policies/approvers/ records the designated
  approver and alternate for MOC, BU, and Red Hat, and the teams that may be
  named as a policy's responsible-team. It is supporting content, kept as
  <name>/README.md so the link resolves both on GitHub and on the published
  site, and excluded from the policies collection so it is not listed as a
  policy in its own right. The approver and contact entries are still TBD.

- The repository README gains an "Approving a policy" section summarising the
  process, including the steps taken once the last institution approves. It
  states that the policy governs where the two differ. The heading is named
  rather than left as "Approval" so its anchor does not shift when sections
  are added above it. Also corrects the policy directory path in the
  "Creating a new policy" example.

- templates/policy is rebuilt to produce a conforming policy: the eight
  required sections in order, the "None." convention, and a Version History
  table with a Type column.

A policy carries no approval date in its frontmatter. The date it was last
approved is the date of the most recent Normative row of its Version History,
so there is a single place to update and no second copy that can drift.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@github-actions github-actions Bot added the ops-policy This is a policy document label Nov 19, 2026

@hpdempsey hpdempsey left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good. My only question is actually not about the policy docs content, but about what a "Responsible team" is defined as. It seems that there are NIST examples of responsible teams given, but there is no analog to this example in the MOC or Red Hat goups. Do we just consider the Red Hat folks all together as a responsible team, and same for the current MOC folks?

Discussed the above questions and the intent is to define an appropriate responsible team as needed for each policy, not matter what org they are from. The org is not the the responsible team. Makes sense.

As an extra note, we should revise the existing already-approved policy as a low priority task when we have time. This is so that all the policies will be consistent eventually.

This all seems workable.

@hpdempsey hpdempsey left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved after some discussion. No changes needed.


Each institution designates one approver for policy pull requests, and one
alternate who records that institution's approval when the designated approver
is the author of the pull request. These roles are per institution, not per

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or the designated approver is not available.

Should we cover what to do if both are unavailable or is that over the top?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As written the policy change will remain unapproved until one of them is available. That seems the right response beyond the ramp up period.

The official list of approvers is supplemental content so the approvers can update the list if someone will be unavailable for a while. However, the fact that it is one per partner is normative content so a partner can't be completely excluded.

Comment thread README.md
> The `main` ruleset does not dismiss approvals on push, so this final commit
> does not invalidate the approvals already recorded. The ruleset requires two
> approving reviews; the requirement that one come from each institution is
> enforced by the approvers, not by GitHub.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we could enforce via github - I agree we should not at this time.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with both statements - automatic enforcement is a nice to have for now. We can consider adding a covenant that approvers agree in the future for this and other aspects of governance. But we don't need this now and we'll have a better sense of what we need later.

@dsmk

dsmk commented Nov 20, 2026

Copy link
Copy Markdown
Author

@msdisme @hpdempsey I made two small changes to the text.

  1. I made it so the length of the comment period is in one spot to get rid of inconsistencies. That location is normative so future updates to the length require full approval which seems correct.
  2. I added language indicating that approvers need to publicize the pull request to the appropriate commenters for feedback. That seemed better than getting into the weeds of specifying which policies might need feedback from different groups (for example, OGC for something that impacts contract language).

Let me know what you think.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ops-policy This is a policy document

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants