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
ckan · Dec 16, 2013 · 84fc1b8 · 84fc1b8
1 parent b3dff01
commit 84fc1b8
Show file tree

Hide file tree

Showing 19 changed files with 109 additions and 96 deletions.
diff --git 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/...ding-standards/ckan-code-architecture.rst → doc/contributing/architecture.rst b/...ding-standards/ckan-code-architecture.rst → doc/contributing/architecture.rst
diff --git a/doc/contributing/coding-standards/index.rst b/doc/contributing/coding-standards/index.rst
diff --git a/doc/contributing/commit-messages.rst b/doc/contributing/commit-messages.rst
@@ -0,0 +1,37 @@
+=======================
+Writing commit messages
+=======================
+
+We use the version control system `git <http://git-scm.com/>`_ 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/...coding-standards/css-coding-standards.rst → doc/contributing/css.rst b/...coding-standards/css-coding-standards.rst → doc/contributing/css.rst
diff --git a/.../coding-standards/database-migrations.rst → doc/contributing/database-migrations.rst b/.../coding-standards/database-migrations.rst → doc/contributing/database-migrations.rst
diff --git a/...contributing/documentation-guidelines.rst → doc/contributing/documentation.rst b/...contributing/documentation-guidelines.rst → 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 <https://github.com/okfn/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 <https://github.com/okfn/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
@@ -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 <http://lesscss.org/>`_ (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/...oding-standards/html-coding-standards.rst → doc/contributing/html.rst b/...oding-standards/html-coding-standards.rst → doc/contributing/html.rst
diff --git 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
@@ -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
@@ -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/...standards/javascript-coding-standards.rst → doc/contributing/javascript.rst b/...standards/javascript-coding-standards.rst → 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
@@ -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 <http://docs.ckan.org/en/latest/test.html>`_.
 
    - 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/...ing-standards/python-coding-standards.rst → doc/contributing/python.rst b/...ing-standards/python-coding-standards.rst → doc/contributing/python.rst
diff --git a/doc/contributing/reviewing.rst 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/...ng-standards/testing-coding-standards.rst → doc/contributing/testing.rst b/...ng-standards/testing-coding-standards.rst → doc/contributing/testing.rst
diff --git a/...ding-standards/upgrading-dependencies.rst → doc/contributing/upgrading-dependencies.rst b/...ding-standards/upgrading-dependencies.rst → doc/contributing/upgrading-dependencies.rst
diff --git 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`.
 
 
 -------------------------------------------------