Commits

Jon Waltman committed a5009a3

devguide: Add guidelines for core developers

Comments (0)

Files changed (1)

 
 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
-committing the changes.
-
-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
-being committed.
+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.
 
 
 Getting Started
 
 These are the basic steps needed to start developing on Sphinx.
 
-.. todo::
-
-   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 BitBucket interface.
 
-   The pull request will be reviewed and if approved, merged by one of the
-   Sphinx developers.
+#. Wait for a core developer to review your changes.
+
+
+Core Developers
+~~~~~~~~~~~~~~~
+
+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
+tracker.
+
+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
+  encouraged.
 
 
 Coding Guide
 * Use the included :program:`utils/check_sources.py` script to check for
   common formatting issues (trailing whitespace, lengthy lines, etc).
 
+* Add appropriate unit tests.
+
 
 Debugging Tips
 ~~~~~~~~~~~~~~
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.