Skip to content

Commit

Permalink
docs: Add maintainer community standards
Browse files Browse the repository at this point in the history
Adds a few explicit community standards for maintainers in the repo
maintenance howto.
  • Loading branch information
arbrandes authored and feanil committed May 15, 2024
1 parent dddc5af commit 861ea3e
Showing 1 changed file with 84 additions and 0 deletions.
84 changes: 84 additions & 0 deletions source/developers/how-tos/maintain-a-repo.rst
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,90 @@ outlined in :doc:`OEP-54 <openedx-proposals:processes/oep-0054-core-contributors

.. _CCs Wiki Page: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3156344833/Core+Contributors+to+the+Open+edX+Project

Hold Yourself to Community Standards
************************************

A prerequisite for a Maintainer is to be a Core Contributor. Part of what this
means is that you must hold yourself to the same standards as any CC - any
contributor, really - in your repository. You are still a member of the
community, after all!

Here are a few rules-of-thumb to keep in mind:

* Participate! Make yourself available in the several community communication
channels - `Discourse`_, `Slack`_, `working group meetings`_, and, of course,
`Github issues`_ - to discuss matters related to your maintenance role
publicly. Don't restrict yourself to private conversation channels: this
would make for an opaque project.

.. _Discourse: https://discuss.openedx.org/

.. _Slack: https://openedx.slack.com/

.. _working group meetings: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3707371565/Active+Working+Groups#Joining-Working-Group-Meetings

.. _GitHub issues: https://github.com/openedx

* Treat any change you or your organization want to make to the codebase as an
open source contribution. This means that any and all PRs must be properly
reviewed by somebody other than the submitter. And if the change is
user-facing, it must necessarily undergo the public `Product Review Process`_.

.. _Product Review Process: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3875962884/How+to+submit+an+open+source+contribution+for+Product+Review

.. important::

Adding a feature toggle around a piece of code does not exempt it from being
put through the Product Review Process! Even experiments must be approved
beforehand, for even if a feature is not shown by default, the code that
builds it must still be dealt with by the community as part of the
maintenance, testing, and release processes.

* Please do not use the main branch as a way to debug your deployments.
Commits to ``main`` or ``master`` should not contain debugging code unless
there's value in it staying there permanently (in which case it would likely
have to sit behind a runtime ``DEBUG`` toggle).

* Your own PRs should have full descriptions, including testing instructions
and screenshots: anybody should be able to understand not only the How, but
the Why. Descriptions consisting solely of a link to a private page are a
big no-no! Hint: Try viewing your link in an incognito browser to see if it
is publicly available.

* Just because you've been entrusted with write access doesn't mean you should
use the repository as you would a personal one:

* Always consult the community with respect to important changes. Possibly
even small ones! When in doubt, go public.

* Unless there's communal value in creating a new public git branch (such as
feature branches, for instance), you should prefer to create PR branches on
personal or organizational Github forks. It is just as easy to issue PRs
from them, and it avoids branch pollution in the main repository. Plus,
it's what regular community members have to do to contribute: it's an
opportunity to lead by example!

* If the repository you maintain is an official part of the Open edX release,
make sure any and all incoming changes are developed with the next one in
mind. In other words, even if they come from your own team, and even if your
organization's deployment method is far from standard, PRs must, among other
things:

* Work with the current officially recommended installation method, which at
the time of writing is `Tutor`_;

* Not contain strings that are not properly internationalized;

* Not contain code, strings, variable names, or feature flags that are
organization- or site-specific.

.. note::

Changes to MFEs must futher conform to the `Requirements for an MFE`_ as
established by the Build Test Release Working Group. Failing to do so would
make the MFE in question ineligible for release.

.. _Requirements for an MFE: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3561521275/Requirements+for+an+MFE

Congratulations!
****************
Expand Down

0 comments on commit 861ea3e

Please sign in to comment.