Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

initial maintainers and governance framework #31

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions GOVERNANCE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Policy and Procedure


## Maintainers

|Maintainer|Role|
|---|---|
|*Dan Harris|CSC Operations|

Choose a reason for hiding this comment

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

We may want to keep the roles aligned with recognized Center categories (groups, teams, etc.). So maybe CSC Operations is ACO (group) or User Operations (team); CSC Applications would be CSSO (group) or User and Applications Support (team). I like the team labels, as it raises visibility of the things we do within the Center and the groups.

Copy link
Contributor

Choose a reason for hiding this comment

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

+1 on teams

|*Kevin Sayers|CSC Applications|
Copy link
Collaborator

Choose a reason for hiding this comment

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

We probably need to update this table

|Chris Chang|CSC Applications|
|Ethan Young|CSC Applications|
|Tim Kaiser|CSC Applications|
|John Leicht|CSC Operations|

_\* indicates repo admin_

## Maintainership


## Adding maintainers


## Removing maintainers


## How are decisions made?


## Conflict Resolution
79 changes: 79 additions & 0 deletions MAINTAINERS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# Maintainer Guidelines

Choose a reason for hiding this comment

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

We might benefit from a sense of the Git-fu a maintainer should have. For those who aren't able to develop that level, is there a different workflow than the more advanced folks? Maybe a "Content Maintainer" would work through the Github interface only on existing material via the editing interface and the master branch, and a "Content Creator" would have more expectations around PRs, reviews, creation, branches, merging, etc.

Reading further, I think I see now the intent. I'm a little concerned that the iterative PR/review process is heavyweight enough to put some folks off of contributing. What might a process be for someone who has ideas for improvement, but doesn't have a Git background?

**This guide is for maintainers.** These people have **write
access** to NREL HPC's repository and help merge the contributions of
others.

If you have something to contribute, please see the [Contributing Guide](CONTRIBUTING.md).

This is a living document - if you see something out of date or missing,
speak up!

## What are a maintainer's responsibilities?

It is every maintainer's responsibility to:

* Expose a clear roadmap for improving the repository.

Choose a reason for hiding this comment

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

"Expose" is a little vague. I think Lex may be the only project I've seen at NREL with a clear roadmap, and even that might be debated by those who were doing the work. Not sure what this bullet means.

* Deliver prompt feedback and decisions on pull requests.
* Be available to anyone with questions, bug reports, criticism etc. on the repository.
This includes GitHub issues and pull requests.
* Make sure the repository respects the philosophy, design and roadmap of the project.

## How are decisions made?

This project is an open-source project with an open design philosophy. This
means that the repository is the source of truth for EVERY aspect of the
project, including its philosophy, design, and roadmap. *If it's
part of the project, it's in the repo. It's in the repo, it's part of
the project.*

As a result, all decisions can be expressed as changes to the
repository.

All decisions affecting this project, big and small, follow the same procedure:

1. Open a pull request.
Anyone can do this.
2. Discuss the pull request.
Anyone can do this.
3. Review the pull request.
The relevant maintainers do this (see below [Who decides what?](#who-decides-what)).
Changes that affect project management (changing policy, cutting releases, etc.) are [proposed and voted on](GOVERNANCE.md).
4. Merge or close the pull request.
The relevant maintainers do this.

### I'm a maintainer, should I make pull requests too?

Yes. Nobody should ever push to master directly. All changes should be

Choose a reason for hiding this comment

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

Are the various dev branches expected to go away once this repo reaches a certain maturity? If not, are direct pushes to a branch other than master permitted?

Copy link
Contributor

Choose a reason for hiding this comment

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

I agree I think we need to clarify this more. Master (code samples) and gh-pages should both not be pushed to directly. Archived should also probably be not pushed to.

My opinion is creating dev branches in the repo works for maintainers, makes it easier to collaborate among ourselves compared to forking -> PR. Here direct pushes should be allowed. Contributors would do the fork->PR workflow.

Copy link
Contributor

@KevinSayers KevinSayers Mar 2, 2022

Choose a reason for hiding this comment

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

We should add branch rules to prevent pushing to master and the gh-pages branch. Also I suggest we change master branch to something more descriptive.

made through a pull request.

## Who decides what?

All decisions are pull requests, and the relevant maintainers make
decisions by accepting or refusing the pull request. Review and acceptance
by anyone is denoted by adding a comment in the pull request.
However, only currently listed `MAINTAINERS` are counted towards the required
two Reviews. In addition, if a maintainer has created a pull request, they cannot
count toward the two Review rule (to ensure equal amounts of review for every pull
request, no matter who wrote it).

Overall the maintainer system works because of mutual respect.
The maintainers trust one another to act in the best interests of the project.
Sometimes maintainers can disagree and this is part of a healthy project to represent the points of view of various people.
In the case where maintainers cannot find agreement on a specific change, maintainers should use the [governance procedure](GOVERNANCE.md) to attempt to reach a consensus.

### How are maintainers added?

The best maintainers have a vested interest in the project. Maintainers
are first and foremost contributors that have shown they are committed to
the long term success of the project. Contributors wanting to become
maintainers are expected to be deeply involved in contributing code,
pull request review, and triage of issues in the project for more than two months.

Just contributing does not make you a maintainer, it is about building trust with the current maintainers of the project and being a person that they can depend on to act in the best interest of the project.
The final vote to add a new maintainer should be approved by the [governance procedure](GOVERNANCE.md).

### How are maintainers removed?

When a maintainer is unable to perform the [required duties](#what-are-a-maintainers-responsibilities) they can be removed by the [governance procedure](GOVERNANCE.md).
Issues related to a maintainer's performance should be discussed with them among the other maintainers so that they are not surprised by a pull request removing them.

Choose a reason for hiding this comment

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

Does this sentence belong in the governance procedure under Removing maintainers, or here?

Copy link
Collaborator

Choose a reason for hiding this comment

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

Governance makes more sense, but a quick link here doesn't hurt either.