diff --git a/docs/contributing.rst b/docs/contributing.rst index 7378176..98d1af8 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -2,10 +2,15 @@ Contributing ============ +.. index:: Contributing + .. note:: Before you begin working on your contribution, please read and become familiar with the design_ of ``django-admin2``. The design_ document should hopefully make it clear what our constraints and goals are for the project. .. _design: https://django-admin2.readthedocs.org/en/latest/design.html +.. index:: + single: Contributing; Setup + Setup ===== @@ -39,6 +44,9 @@ Try the example projects .. _virtualenv: http://www.virtualenv.org/en/latest/ .. _virtualenvwrapper: http://virtualenvwrapper.readthedocs.org/en/latest/ +.. index:: + single: Contributing; Issues + Issues! ======= @@ -54,6 +62,10 @@ Tips #. Since this project will live on inheritance, all views are Class-Based. #. Familiarize yourself with the project design_ document. +.. index:: + single: Contributing; Topic Branches + single: Contributing; Pull Requests + Setting up topic branches and generating pull requests ====================================================== @@ -110,6 +122,9 @@ a reviewer asks for changes, you do not need to close the pull and reissue it after making changes. Just make the changes locally, push them to GitHub, then add a comment to the discussion section of the pull request. +.. index:: + single: Contributing; Pulling Upstream Changes + Pull upstream changes into your fork regularly ================================================== @@ -122,6 +137,9 @@ To pull in upstream changes:: For more info, see http://help.github.com/fork-a-repo/ +.. index:: + single: Contributing; Pulling with Rebase + Advanced git users: Pull with rebase ------------------------------------ @@ -131,11 +149,19 @@ This will pull and then reapply your work on top of the upcoming changes:: It saves you from an extra merge, keeping the history cleaner, but it's potentially dangerous because you're rewriting history. For more info, see http://gitready.com/advanced/2009/02/11/pull-with-rebase.html +.. index:: + single: Contributing; Getting your Pull Requests Accepted + +.. index:: Getting your Pull Request Accepting + How to get your pull request accepted ===================================== We want your submission. But we also want to provide a stable experience for our users and the community. Follow these rules and you should succeed without a problem! +.. index:: + single: Getting your Pull Request Accepting; Run the tests! + Run the tests! -------------- @@ -145,6 +171,10 @@ Before you submit a pull request, please run the entire django-admin2 test suite The first thing the core committers will do is run this command. Any pull request that fails this test suite will be **immediately rejected**. +.. index:: + single: Getting your Pull Request Accepting; Don't reduce test coverage! + + If you add code/views you need to add tests! -------------------------------------------- @@ -168,12 +198,18 @@ Examples:: # run all tests from application ``blog`` and the test named # ``test_register`` on the ``djadmin2.Admin2Test`` testcase. python runtests.py djadmin2.Admin2Test.test_register blog + +.. index:: + single: Getting your Pull Request Accepting; Don't mix code changes with whitespace cleanup Don't mix code changes with whitespace cleanup ---------------------------------------------- If you change two lines of code and correct 200 lines of whitespace issues in a file the diff on that pull request is functionally unreadable and will be **immediately rejected**. Whitespace cleanups need to be in their own pull request. +.. index:: + single: Getting your Pull Request Accepting; Keep your pull requests limited to single issues + Keep your pull requests limited to a single issue -------------------------------------------------- @@ -186,7 +222,6 @@ django-admin2 pull requests should be as small/atomic as possible. Large, wide-s Best Practices -------------- - As much as possible, we follow the advice of the `Two Scoops of Django`_ book. Periodically the book will be referenced either for best practices or as a blunt object by the project lead in order to end bike-shedding. .. _`Two Scoops of Django`: https://2scoops.org