Skip to content

Latest commit

 

History

History
300 lines (203 loc) · 10.2 KB

CONTRIBUTING.rst

File metadata and controls

300 lines (203 loc) · 10.2 KB
Raw

Contributing to CKAN

CKAN is free open source software and code contributions are welcome, whether they're bug reports, source code, documentation or translations. The sections below will walk you through our processes for making different kinds of contributions to CKAN.

Reporting Issues

If you've found a bug in CKAN, open a new issue on CKAN's GitHub Issues (try searching first to see if there's already an issue for your bug).

Translating CKAN

For contributing translations to CKAN, see Translating CKAN.

i18n

Coding Standards

When writing code for CKAN, try to respect our coding standards:

ckan-coding-standards python-coding-standards html-coding-standards css-coding-standards javascript-coding-standards testing-coding-standards

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.

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:

[#2505] Update source install instructions

Following feedback from markw (see #2406).

Frontend Development Guidelines

frontend-development templating resources template-tutorial template-blocks javascript-module-tutorial

Writing Documentation

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.

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.

For how to contribute to the offical CKAN documentation at docs.ckan.org, see the documentation guidelines.

documentation-guidelines

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. This section will walk you through the steps for making a pull request.

  1. Create a git branch

    Each logically separate piece of work (e.g. a new feature, a bug fix, a new docs page, or a set of improvements to a docs page) should be developed on its own branch forked from the master branch.

    The name of the branch should include the issue number (if this work has an issue in the CKAN issue tracker), and a brief one-line synopsis of the work, for example:

    2298-add-sort-by-controls-to-search-page

  2. Fork CKAN on GitHub

    Sign up for a free account on GitHub and fork CKAN, so that you have somewhere to publish your work.

    Add your CKAN fork to your local CKAN git repo as a git remote. Replace USERNAME with your GitHub username:

    git remote add my_fork https://github.com/USERNAME/ckan

  3. Commit and push your changes

    Commit your changes on your feature branch, and push your branch to GitHub. For example, make sure you're currently on your feature branch then run these commands:

    git add doc/my_new_feature.rst
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.

  4. Send a pull request

    Once your work on a branch is complete and is ready to be merged into the master branch, create a pull request on GitHub. A member of the CKAN team will review your work and provide feedback on the pull request page. The reviewer may ask you to make some changes. Once your pull request has passed the review, the reviewer will merge your code into the master branch and it will become part of CKAN!

    When submitting 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.
    • 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 Writing 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 before submitting your pull request.

      For long-running feature branches, it's a good idea to pull master into the feature branch periodically so that the two branches don't diverge too much.

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,

Upgrading the dependencies

CKAN's dependencies are pinned to specific versions, so we can guarantee that no matter when you install it, you'll always get the same dependencies' versions our code was tested with.

We couldn't simply leave everything in our requirements.txt file, though. Sometimes, we discover that one dependency releases a new version that's incompatible with CKAN, so we need a way to enforce that we won't upgrade it unexpectedly in the future. We also split between dev and non-dev requirements, so production servers don't need to install dependencies only used for testing, for example.

Our dependencies are split in 3 files: requirements.in, requirements.txt, and dev-requirements.txt.

requirements.in

Contains our direct dependencies (i.e. not our dependencies' dependencies), with loosely defined versions. For example, apachemiddleware>=0.1.1,<0.2.

requirements.txt

Contains every dependency, including indirect, pinned to a specific version. Created with pip freeze. For example, simplejson==3.3.1.

dev-requirements.txt

Contains our development dependencies, pinned to a specific version. For example, factory-boy==2.1.1.

We haven't created a dev-requirement.in because we have too few dev dependencies, we don't update them often, and none of them have a known incompatible version.

Steps to upgrade

  1. Create a new virtualenv: virtualenv --no-site-packages upgrading
  2. Install the requirements with unpinned versions: pip install -r requirements.in
  3. Save the new dependencies versions: pip freeze > requirements.txt. We have to do this before installing the other dependencies so we get only what was in requirements.in
  4. Install CKAN: python setup.py develop
  5. Install the development dependencies: pip install -r dev-requirements.txt
  6. Run the tests to make sure everything still works (see test).
    • If not, try to fix the problem. If it's too complicated, pinpoint which dependency's version broke our tests, find an older version that still works, and add it to requirements.in. Go back to step 1.
  7. Navigate a bit on CKAN to make sure the tests didn't miss anything. Review the dependencies changes and their changelogs. If everything seems fine, go ahead and fill a pull request (see making a pull request).