The recommended way for new contributors to submit code to Sphinx is to fork
the Mercurial repository on BitBucket and then submit a pull request after
-Developers with write access to the main repository are also encouraged to
-create pull requests for non-trivial changes so they may be reviewed before
+committing the changes. The pull request will then need to be approved by one
+of the core developers before it is merged into the main repository.
These are the basic steps needed to start developing on Sphinx.
- Recommend using named branches?
#. Create an account on BitBucket.
#. Fork the main Sphinx repository (`birkenfeld/sphinx
#. Submit a pull request from your repository to ``birkenfeld/sphinx`` using
- The pull request will be reviewed and if approved, merged by one of the
+#. Wait for a core developer to review your changes.
+The core developers of Sphinx have write access to the main repository. They
+can commit changes, accept/reject pull requests, and manage items on the issue
+You do not need to be a core developer or have write access to be involved in
+the development of Sphinx. You can submit patches or create pull requests
+from forked repositories and have a core developer add the changes for you.
+The following are some general guidelines for core developers:
+* Questionable or extensive changes should be submitted as a pull request
+ instead of being committed directly to the main repository. The pull
+ request should be reviewed by another core developer before it is merged.
+* Trivial changes can be committed directly but be sure to keep the repository
+ in a good working state and that all tests pass before pushing your changes.
+* When committing code written by someone else, please attribute the original
+ author in the commit message and any relevant :file:`CHANGES` entry.
+* Using Mercurial named branches other than ``default`` and ``stable`` is not
* Use the included :program:`utils/check_sources.py` script to check for
common formatting issues (trailing whitespace, lengthy lines, etc).
+* Add appropriate unit tests.