Becoming a CKAN Developer
From CKAN
All CKAN code is managed in Git repositories in the OKFN Github.
In order to contribute code changes to CKAN you need to understand how we structure our code, the policies and conventions we use when developing and the core git commands we use. These are all covered in here.
Contents |
Check-In Policy
CKAN is open source and contributions are welcome. However, we have some guidelines for check-ins to ensure that all developers can work well together.
Check-ins
- Work on the right branch - see Commit Policy below.
- Write tests for all changes. Unit tests go into ckan/tests/{area}/ and functional tests go into ckan/tests/functional/ . Tests describe intent and stop the code regressing in the future.
- Run all the tests before you commit your code. It only takes 5 minutes!
nosetests --ckan ckan/tests
Starting out
- It's good to fork the CKAN repo and push your changes to your fork.
- If you contribute regularly you can ask for access rights to contribute directly to the OKF repo - ask for these on ckan-dev list.
Workflow
Big or Medium changes:
- Create a ticket with your suggestion and design detail as necessary.
- Do it, whilst leaving the 'master' branch of the repo in a good state at all times (i.e. builds and works). Use another branch or Github if it will require more than one check in.
- When done, merge in as necessary and close the ticket
Exceptions:
- If it is an utterly trivial change, (doesn't change more than a couple of lines or is just in docs/tests/pip-requirements, that doesn't fix a bug that has been on a release) then include '[xs]' in the comment and you don't need a ticket or branch.
Don't break the build
- Keep an eye on buildbot to make sure you don't break the build. If you're a regular developer, ask to be added to the buildbot emails. Don't wait to be nagged by other frustrated developers ;-)
- If you break the build, please fix it quickly. If it may take time then email [CkanDev ckan-dev] to let others know what the plan is.
Commit Policy
CKAN is stored in Github repos. This policy covers development and branching policy for these repos.
In general: One Branch per Feature and Defect
Not only is it good practice to separate different features in the repo, but we are very keen to not have half-completed big features in the master branch.
We will be following the process described in (1) but applied to Github. Key aspects:
- A (named) branch will be created for each feature or defect (bug), unless it is almost certain that the ticket only requires one changeset. Branch naming convention:
- defect-{ticket-number}[-optional-name] e.g. defect-902-my-bad-bug
- feature-{ticket-number}[-optional-name] e.g. feature-903-my-amazing-feature
- A (named) branch will be created for each release: release-v{release-number} e.g. release-v1.3
Workflow is described in the section above.
Merging Branches back in
Please use --no-ff (no fast forward), otherwise it may automatically collapse a branch if it can, and you lose the record of intention to do a feature separately to the master.
git checkout master
git pull
git merge --no-ff {branch-name}
git push
