Topic: Using Git and Github
Topic type:
Collection of topics, weblinks, and documents to help with using Git and Github.
The Kete project uses git and http://github.com/ to do version control of its code. This is also how we collaborate on the Kete codebase.
Here's what you can do with git and github and Kete:
- browse the codebase online and comment on any piece of code here: http://github.com/kete/kete
- view individual changes to the codebase also via commits pages on github as above
- get a hold of the codebase to install by cloning Kete as described in the downloads page
- update your local clone of Kete to grab the latest features or bugfixes (doing a "git pull" or "git fetch" and a "git merge", see links for guides)
- contribute code as a Kete software developer as described below (no pre-approval necessary)
Being a Kete Developer
Here are the details of what you must do to contribute code to the Kete Project:
- Install Git from http://git-scm.com/
- Register at github.com
- If you have changes to contribute to Kete, go to the Kete repository on github.com, then you must "fork" (see github.com guides) Kete
- Create a ticket for the work you want to do, if there isn't already one. (requires an account on Lighthouseapp)
- Start creating changes in your own repository by creating a branch that is named after the ticket using the following convention: enhancement_ticket#_short_description or bugfix_ticket#_short_description
- Use good commit messages. Clearly mark when your work is an enhancement (new feature) or bugfix and describe the work you have done.
- When you are satisfied your changes are ready to be submitted to the Kete project, make a pull request and a Kete maintainer will review your work for inclusion in the Kete project
This assumes that you have knowledge of Kete's underlying tools; the Ruby language, the Ruby on Rails web framework, HTML, CSS, and Javascript. If not, you'll need to brush up on these before you can contribute anything codewise.
Furthermore, if you're familar with HTML/CSS but not the others, you can always create a theme for others to use. See the theming guides in the Themes basket on this site.
Finally, there is always the possibility of contributing translations in Kete 1.3 and later, which do not need any coding experience at all (only a working copy of Kete in development mode). Take a look at the following topic for more details: General Stratigies for creating a translation of the Kete UI . When you have finished with a translation, create a new ticket and attach the translation yml file.
Important Note: If your code is accepted into the Kete project you will be given credit in code comments, but all code will be transferred to the existing GPL license and copyright will be held by Horowhenua Library Trust which is the non-profit steward of the codebase.
What if your work is not viewed as ready or appropriate for the general Kete project by a maintainer?
If your code simply needs improvement, you will get feedback from the Kete maintainer on what you need to fix.
Possibly you have got no/not enough tests. A good handful of tests accompanying the code goes a long way to helping other developers see what your changes do, and help make supporting the feature in the future easier.
If, however, you have customizations that are deemed as not appropriate for the Kete project at a given time, you are welcome to maintain your own fork and use it as you see fit. That's one of the great things about github. You are also certainly welcome to lobby the larger Kete community here at old.kete.net.nz that it should be included in Kete.
