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`. -------------------------------------------------