From 84fc1b8bebd81f1712e03849edaf4440e6ad7d76 Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Mon, 16 Dec 2013 14:57:26 +0100 Subject: [PATCH] Another contributing docs reorganization Redorder it all into a single docs/contributing/ subdirectory with one table of contents and no sub-sub-directories (except for the frontend guidelines one, which still needs sorting out). This makes it much easier to see what's there (one main table of contents for all of contributing) and navigate. Add _CKAN issue tracker hyperlink target to conf.py. Move commit messages guidelines to their own page. Move reviewing a pull request guidelines to their own page. Fix title style of various titles. A few other small changes --- doc/conf.py | 2 + ...code-architecture.rst => architecture.rst} | 0 doc/contributing/coding-standards/index.rst | 17 ------ doc/contributing/commit-messages.rst | 37 ++++++++++++ .../css-coding-standards.rst => css.rst} | 0 .../database-migrations.rst | 0 ...ation-guidelines.rst => documentation.rst} | 22 ++++--- doc/contributing/frontend/index.rst | 20 +++---- .../html-coding-standards.rst => html.rst} | 0 doc/contributing/i18n.rst | 6 +- doc/contributing/index.rst | 22 ++++++- doc/contributing/issues.rst | 2 +- ...pt-coding-standards.rst => javascript.rst} | 2 +- doc/contributing/pull-requests.rst | 58 +++---------------- ...python-coding-standards.rst => python.rst} | 0 doc/contributing/reviewing.rst | 15 +++++ ...sting-coding-standards.rst => testing.rst} | 0 .../upgrading-dependencies.rst | 0 doc/extensions/best-practices.rst | 2 +- 19 files changed, 109 insertions(+), 96 deletions(-) rename doc/contributing/{coding-standards/ckan-code-architecture.rst => architecture.rst} (100%) delete mode 100644 doc/contributing/coding-standards/index.rst create mode 100644 doc/contributing/commit-messages.rst rename doc/contributing/{coding-standards/css-coding-standards.rst => css.rst} (100%) rename doc/contributing/{coding-standards => }/database-migrations.rst (100%) rename doc/contributing/{documentation-guidelines.rst => documentation.rst} (96%) rename doc/contributing/{coding-standards/html-coding-standards.rst => html.rst} (100%) rename doc/contributing/{coding-standards/javascript-coding-standards.rst => javascript.rst} (99%) rename doc/contributing/{coding-standards/python-coding-standards.rst => python.rst} (100%) create mode 100644 doc/contributing/reviewing.rst rename doc/contributing/{coding-standards/testing-coding-standards.rst => testing.rst} (100%) rename doc/contributing/{coding-standards => }/upgrading-dependencies.rst (100%) diff --git a/doc/conf.py b/doc/conf.py index e5c33312cfc..bff9026ef94 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -62,6 +62,8 @@ .. |nginx_config_file| replace:: /etc/nginx/sites-available/ckan_default .. |reload_nginx| replace:: sudo service nginx reload +.. _CKAN issue tracker: https://github.com/okfn/ckan/issues + ''' # Add any Sphinx extension module names here, as strings. They can be extensions diff --git a/doc/contributing/coding-standards/ckan-code-architecture.rst b/doc/contributing/architecture.rst similarity index 100% rename from doc/contributing/coding-standards/ckan-code-architecture.rst rename to doc/contributing/architecture.rst diff --git a/doc/contributing/coding-standards/index.rst b/doc/contributing/coding-standards/index.rst deleted file mode 100644 index 95c343e50c0..00000000000 --- a/doc/contributing/coding-standards/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -===================== -CKAN Coding Standards -===================== - -When writing code for CKAN, please follow our coding standards: - -.. toctree:: - :maxdepth: 1 - - ckan-code-architecture - python-coding-standards - html-coding-standards - css-coding-standards - javascript-coding-standards - testing-coding-standards - database-migrations - upgrading-dependencies diff --git a/doc/contributing/commit-messages.rst b/doc/contributing/commit-messages.rst new file mode 100644 index 00000000000..ff2de239c33 --- /dev/null +++ b/doc/contributing/commit-messages.rst @@ -0,0 +1,37 @@ +======================= +Writing commit messages +======================= + +We use the version control system `git `_ for our code +and documentation, so when contributing code or docs you'll have to commit +your changes to git and write a git commit message. +Generally, follow the `commit guidelines from the Pro Git book`_: + +- Try to make each commit a logically separate, digestible changeset. + +- The first line of the commit message should concisely summarise the + changeset. + +- Optionally, follow with a blank line and then a more detailed explanation of + the changeset. + +- Use the imperative present tense as if you were giving commands to the + codebase to change its behaviour, e.g. *Add tests for...*, *make xyzzy do + frotz...*, this helps to make the commit message easy to read. + +.. _commit guidelines from the Pro Git book: http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines + +If your commit has an issue in the `CKAN issue tracker`_ put the issue number +at the start of the first line of the commit message like this: ``[#123]``. +This makes the CKAN release manager's job much easier! + +Here's an example of a good CKAN commit message:: + + [#607] Allow reactivating deleted datasets + + Currently if a dataset is deleted and users navigate to the edit form, + there is no state field and the delete button is still shown. + + After this change, the state dropdown is shown if the dataset state is + not active, and the delete button is not shown. + diff --git a/doc/contributing/coding-standards/css-coding-standards.rst b/doc/contributing/css.rst similarity index 100% rename from doc/contributing/coding-standards/css-coding-standards.rst rename to doc/contributing/css.rst diff --git a/doc/contributing/coding-standards/database-migrations.rst b/doc/contributing/database-migrations.rst similarity index 100% rename from doc/contributing/coding-standards/database-migrations.rst rename to doc/contributing/database-migrations.rst diff --git a/doc/contributing/documentation-guidelines.rst b/doc/contributing/documentation.rst similarity index 96% rename from doc/contributing/documentation-guidelines.rst rename to doc/contributing/documentation.rst index 512c702db64..0b4989cba26 100644 --- a/doc/contributing/documentation-guidelines.rst +++ b/doc/contributing/documentation.rst @@ -1,16 +1,20 @@ -======================== -Documentation guidelines -======================== +===================== +Writing documentation +===================== .. _docs.ckan.org: http://docs.ckan.org -The quickest and easiest way to contribute documentation to CKAN is to sign up -for a free GitHub account and simply edit the `CKAN Wiki `_. -Docs started on the wiki can make it onto `docs.ckan.org`_ later. +.. seealso:: + + The quickest and easiest way to contribute documentation to CKAN is to sign up + for a free GitHub account and simply edit the `CKAN Wiki `_. + Docs started on the wiki can make it onto `docs.ckan.org`_ later. + If you do want to contribute to `docs.ckan.org`_ directly, follow the + instructions on this page. -**Tip**: Use the reStructuredText markup format when creating a wiki page, -since reStructuredText is the format that docs.ckan.org uses, this will make -moving the documentation from the wiki into docs.ckan.org later easier. + **Tip**: Use the reStructuredText markup format when creating a wiki page, + since reStructuredText is the format that docs.ckan.org uses, this will make + moving the documentation from the wiki into docs.ckan.org later easier. This section gives some guidelines to help us to write consistent and good quality documentation for CKAN. diff --git a/doc/contributing/frontend/index.rst b/doc/contributing/frontend/index.rst index 0160653ef27..7232c736d46 100644 --- a/doc/contributing/frontend/index.rst +++ b/doc/contributing/frontend/index.rst @@ -1,5 +1,5 @@ =============================== -Frontend Development Guidelines +Frontend development guidelines =============================== .. toctree:: @@ -11,9 +11,9 @@ Frontend Development Guidelines template-blocks javascript-module-tutorial ------------------------------- -Install front end dependencies ------------------------------- +----------------------------- +Install frontend dependencies +----------------------------- The front end stylesheets are written using `LESS `_ (this depends on @@ -39,7 +39,7 @@ style script. $ npm install less nodewatch -------------- -File Structure +File structure -------------- All front-end files to be served via a web server are located in the @@ -202,7 +202,7 @@ factory function. A guide on creating your own modules is located in the :doc:`javascript-module-tutorial` guide. -Publisher/Subscriber +Publisher/subscriber ==================== There is a simple pub/sub module included under ``ckan.pubsub`` it's @@ -289,7 +289,7 @@ And we name the translate function passed into ``ckan.module()`` ``_``. }; }); -Life Cycle +Life cycle ========== CKAN modules are intialised on dom ready. The ``ckan.module.initialize()`` @@ -348,8 +348,8 @@ retrieving them. }); -jQuery Plug-ins -=============== +jQuery plugins +============== Any functionality that is not directly related to ckan should be packaged up in a jQuery plug-in if possible. This keeps the modules @@ -359,7 +359,7 @@ other sites. Examples of these are ``jQuery.fn.slug()``, ``jQuery.fn.slugPreview()`` and ``jQuery.proxyAll()``. -Unit Tests +Unit tests ========== There is currently a test suite available at: diff --git a/doc/contributing/coding-standards/html-coding-standards.rst b/doc/contributing/html.rst similarity index 100% rename from doc/contributing/coding-standards/html-coding-standards.rst rename to doc/contributing/html.rst diff --git a/doc/contributing/i18n.rst b/doc/contributing/i18n.rst index 6763de6e7e5..ffd72f88144 100644 --- a/doc/contributing/i18n.rst +++ b/doc/contributing/i18n.rst @@ -1,6 +1,6 @@ -====================================== -Internationalizing and localizing CKAN -====================================== +================ +Translating CKAN +================ CKAN is used in many countries, and adding a new language to the web interface is a simple process. diff --git a/doc/contributing/index.rst b/doc/contributing/index.rst index 0ef49dece81..f2e62229d36 100644 --- a/doc/contributing/index.rst +++ b/doc/contributing/index.rst @@ -10,12 +10,28 @@ they're bug reports, source code, documentation or translations. The following documents will walk you through our processes for making different kinds of contributions to CKAN: +.. If editing this, note that these are roughly ordered with the most simple + forms of contribution (for non-developers) first, and then the more advanced + technical topics after. + .. toctree:: :maxdepth: 1 issues i18n - documentation-guidelines - coding-standards/index - frontend/index + + commit-messages pull-requests + reviewing + + documentation + architecture + css + html + javascript + python + testing + frontend/index + + database-migrations + upgrading-dependencies diff --git a/doc/contributing/issues.rst b/doc/contributing/issues.rst index c5e440d2b3e..43517f8336e 100644 --- a/doc/contributing/issues.rst +++ b/doc/contributing/issues.rst @@ -1,5 +1,5 @@ ================ -Reporting Issues +Reporting issues ================ If you've found a bug in CKAN, open a new issue on CKAN's `GitHub Issues`_ (try diff --git a/doc/contributing/coding-standards/javascript-coding-standards.rst b/doc/contributing/javascript.rst similarity index 99% rename from doc/contributing/coding-standards/javascript-coding-standards.rst rename to doc/contributing/javascript.rst index 527bcde24a1..cb4a3a8798f 100644 --- a/doc/contributing/coding-standards/javascript-coding-standards.rst +++ b/doc/contributing/javascript.rst @@ -1,5 +1,5 @@ =========================== -Javascript coding standards +JavaScript coding standards =========================== ---------- diff --git a/doc/contributing/pull-requests.rst b/doc/contributing/pull-requests.rst index 503bbff823d..98b05c9f4dd 100644 --- a/doc/contributing/pull-requests.rst +++ b/doc/contributing/pull-requests.rst @@ -1,8 +1,6 @@ ---------------------- -Making a Pull Request ---------------------- - -.. _CKAN issue tracker: https://github.com/okfn/ckan/issues +===================== +Making a pull request +===================== Once you've written some CKAN code or documentation, you can submit it for review and merge into the central CKAN git repository by making a pull request. @@ -44,8 +42,8 @@ This section will walk you through the steps for making a pull request. git commit -m "Add docs for my new feature" git push my_fork my_branch - When writing your git commit messages, try to follow the `Commit Messages`_ - guidelines. + When writing your git commit messages, try to follow the + :doc:`commit-messages` guidelines. #. Send a pull request @@ -62,14 +60,14 @@ This section will walk you through the steps for making a pull request. - Your branch should contain one logically separate piece of work, and not any unrelated changes. - - You should have good commit messages, see `Commit Messages`_. + - You should have good commit messages, see :doc:`commit-messages`. - Your branch should contain new or changed tests for any new or changed code, and all the CKAN tests should pass on your branch, see `Testing CKAN `_. - Your branch should contain new or updated documentation for any new or - updated code, see :doc:`documentation-guidelines`. + updated code, see :doc:`documentation`. - Your branch should be up to date with the master branch of the central CKAN repo, so pull the central master branch into your feature branch @@ -80,45 +78,3 @@ This section will walk you through the steps for making a pull request. much. .. _create a pull request on GitHub: https://help.github.com/articles/creating-a-pull-request - - -Merging a Pull Request -====================== - -If you're reviewing a pull request for CKAN, when merging a branch into master: - -- Use the ``--no-ff`` option in the ``git merge`` command, - ---------------- -Commit Messages ---------------- - -Generally, follow the `commit guidelines from the Pro Git book`_: - -- Try to make each commit a logically separate, digestible changeset. - -- The first line of the commit message should concisely summarise the - changeset. - -- Optionally, follow with a blank line and then a more detailed explanation of - the changeset. - -- Use the imperative present tense as if you were giving commands to the - codebase to change its behaviour, e.g. *Add tests for...*, *make xyzzy do - frotz...*, this helps to make the commit message easy to read. - -.. _commit guidelines from the Pro Git book: http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines - -If your commit has an issue in the `CKAN issue tracker`_ put the issue number -at the start of the first line of the commit message like this: ``[#123]``. -This makes the CKAN release manager's job much easier! - -Here's an example of a good CKAN commit message:: - - [#607] Allow reactivating deleted datasets - - Currently if a dataset is deleted and users navigate to the edit form, - there is no state field and the delete button is still shown. - - After this change, the state dropdown is shown if the dataset state is - not active, and the delete button is not shown. diff --git a/doc/contributing/coding-standards/python-coding-standards.rst b/doc/contributing/python.rst similarity index 100% rename from doc/contributing/coding-standards/python-coding-standards.rst rename to doc/contributing/python.rst diff --git a/doc/contributing/reviewing.rst b/doc/contributing/reviewing.rst new file mode 100644 index 00000000000..a26ae504e25 --- /dev/null +++ b/doc/contributing/reviewing.rst @@ -0,0 +1,15 @@ +==================================== +Reviewing and merging a pull request +==================================== + +.. todo:: + + Put some more detailed docs here about how to review a CKAN pull request. + +---------------------- +Merging a pull request +---------------------- + +If you're reviewing a pull request for CKAN, when merging a branch into master: + +- Use the ``--no-ff`` option in the ``git merge`` command diff --git a/doc/contributing/coding-standards/testing-coding-standards.rst b/doc/contributing/testing.rst similarity index 100% rename from doc/contributing/coding-standards/testing-coding-standards.rst rename to doc/contributing/testing.rst diff --git a/doc/contributing/coding-standards/upgrading-dependencies.rst b/doc/contributing/upgrading-dependencies.rst similarity index 100% rename from doc/contributing/coding-standards/upgrading-dependencies.rst rename to doc/contributing/upgrading-dependencies.rst diff --git a/doc/extensions/best-practices.rst b/doc/extensions/best-practices.rst index b251509f4bb..eeee5118887 100644 --- a/doc/extensions/best-practices.rst +++ b/doc/extensions/best-practices.rst @@ -7,7 +7,7 @@ Best practices for writing extensions Follow CKAN's coding standards ------------------------------ -See :doc:`/contributing/coding-standards/index`. +See :doc:`/contributing/index`. -------------------------------------------------