Development of KwaMoja
All code contributions must comply with the Coding Guidelines
At KwaMoja we use Git for our source code management. The main repository is held here. This contains two branches, master and develop. The master branch is the one that will be used for releases, and any new work should be merged into the develop branch.
To start developing KwaMoja with git, you should first get yourself an account with GitHub. To get yourself a copy of the KwaMoja code to work on, sign in to your account, and go to the site of the main repository here. In the top right hand corner you should see a button called "Fork", looking like this: Click this button and github will create a fork of the KwaMoja code in your own repository.
To download a copy of the code to your local machine you will need git installed. To install on Linux should be easy as it should be in your distributions repositories. There are instructions for installing on mac or windows here.
To clone your github repository just issue the following command:
git clone https://github.com/xxxxxxxxxx/KwaMoja.git
where xxxxxxxxxx is your github user name. This will create a complete copy of the repository in a sub-directory of the current directory called KwaMoja.
In order to work on the code you need to use the develop branch. At this stage you will be in the master branch. To change to the develop branch, issue the following command:
git checkout develop
To ensure that you have the correct branch checked out you can run the command:
which should give you output something like this:
the * telling you which branch is the current one. You can now make your changes to the code.
Once you have completed changes to a file you need to add those changes to the git index. This is achieved with the following command:
git add Xxxxxxxxz.php
where Xxxxxxxxz.php is the name of the file to be added. Once the fix or feature you are working on is complete you need to commit it to your local repository and then push it to your github.com site. This is done with the following two commands:
Finally having completed your changes you now wish to make a request to KwaMoja/KwaMoja to pull in your changes into the main repository. To do this you must enter your own KwaMoja repository under your own login. There you should see a button called Pull Request, and looking like this: On the new screen you should set the target repository to the one you wish the pull request to be sent to (normally KwaMoja/KwaMoja), and the base branch should normally be set to develop. The head repository should be your own repository, and the head branch should be set to the one where you did the work, normally develop. Github will then automatically show you the differences between these branches, which should be the work you have just done. At this stage you should check that everything appears to be ok. When you are happy, click on the green Create Pull Request button. This will send the pull request to the administrator of the KwaMoja repository.
This request will now be reviewed and either be accepted straight away, or some comment be made on it and you will be notified of that comment.
Obviously the above is a quick overview of the use of Git and GitHub, and there is a huge range of functions that can be used with it. For specific help on github there is a considerable amount of documentation here, and for more general documentation on using Git, a good place to start is here.
No bugs can be closed until they are accompanied by a test, so that any regression errors can be avoided. To write a test use the selenium IDE feature on Firefox.
However it must be remembered that contributing to KwaMoja is about so much more than just writing code. It is vitally important that documentation is kept up to date, that translations are done, and revised every time a string gets changed, queries are answered on the mailing lists and the forums, bugs are reported, and so much more.
A new feature for KwaMoja?
If you have a new feature that you want implemented in KwaMoja, the first step would be to join the developers mailing list, and then write to the list detailing your idea. There are many experienced developers there who can give you some guidance on what you are trying to achieve. Once you have a good feeling for what you are trying to do, then write a full proposal on the wiki and link this to the mailing list discussion. From here a more detailed specification of the feature can be built. If you are not a developer yourself then this is the point that you must get the attention of a developer, and the better the specification the more likely you are to find a developer willing to help.
If you are a developer then you can now clone the develop branch and start working on your feature. Don't forget to frequently push your branch back to github so that other developers can help with your new feature.
When the feature is complete issue a pull request on github, and also make a statement on the mailing list informing others of your work.