Development Process

The Adapto Project uses a typical distributed development process.

First, join the Sourceforge Adapto-project developers mailing list. Second, get a free GitHub user id if you don't already have one. Once you have a GitHub user id, you can contribute to the Adapto Wiki.

To contribute code to Adapto, fork the master egeniq/adapto repository to your own GitHub account. If you intend to actively work on something (a bug fix or new feature), please send a note to the mailing list so the community is aware and everyone can benefit from knowing what you're doing. Successful open source projects are collaborative and depend on everyone staying informed to work together effectively.

Development Steps

Also see Fork A Repo on GitHub.

1. Login to GitHub and fork the master Adapto project to your own GitHub account.

Access the egeniq/adapto project and click the Fork button at the top of the page (just below your login name). Forking is essentially the same as cloning, but with access to GitHub's unique Pull-Request feature for submitting your changes back to the core project team.

2. Clone your Adapto fork to your development system.

How you do this will depend on the protocol you want to use and on your development environment. The Git protocol uses SSH keys instead of passwords, but uses a non-standard port and is generally blocked by corporate firewalls. The HTTPS protocol generally works behind corporate firewalls (although unfortunately not mine), but requires you to type your GitHub login name and password each commit (although they can be temporarily cached). You specify which protocol to use by the format of the source URL in the clone command.

On Windows, I use Git-Extensions with PuTTY/Paegent for managing my SSH keys, and clone using the Read-Write SSH URL shown at the top of my GitHub repo (Clone in Windows is for use with "GitHub for Windows" GH4W, which I tried once but found it too dumbed-down for my liking).

3. Set the "upstream" remote in your local clone.

Setting an upstream remote makes it easy to pull changes from the master Adapto repository to your local clone, which should be done periodically and especially before pushing local changes back to your GitHub fork to avoid a potential mess of 3-way merging if you and the master project have diverged.

Using Git Bash on Windows, I specify the Read-only SSH URL so Git doesn't try authenticating me (because I don't have privileges to the master Adapto repository anyway):

    dale@DALE-T61 /c/xampp/htdocs/adapto (master)
    $ git fetch upstream
    From git://github.com/egeniq/adapto.git
    * [new branch]      master     -> upstream/master
     
    $ git merge upstream/master 

4. Make changes in your local Adapto clone working directory.

Fix a bug, add a feature, or just correct a spelling mistake, it's all good.

5. Commit your changes to your local repository.

Use git add/commit/commit -a to commit your changes locally. If you intend for your changes to be committed to the master repo, make sure you have thoroughly tested your changes at this point. You want the code you push to your GitHub clone to be clean and working, otherwise the history in the master repo can get messy if problems have to be fixed later - and no one wants that if it could have been avoided!

On Windows, I use the Git-Extensions Commit to stage files and commit.

6. Push your local changes to your fork in your GitHub account.

First, pull any changes recently committed to the master Adapto repo into your local clone. If there have been changes, you will need to merge them into your local work before pushing upstream (and to keep everything the simplest, before even pushing to your GitHub fork). In my case shown below, there have been no recent commits to the master Adapto repo.

    dale@DALE-T61 /c/xampp/htdocs/adapto (master)
    $ git pull upstream master
    From git://github.com/egeniq/adapto.git
     * branch            master     -> FETCH_HEAD
    Already up-to-date.

On Windows, I use Git-Extensions Pull. Make sure you select the master branch in the dialogue because upstream is not the default configured remote for master (so it must be specified).

After resolving any conflicts, push your local changes to your fork in your GitHub account.

    $ git push origin master

On Windows, I use Git-Extensions Push to push my local master branch to the origin remote (my GitHub fork).

7. Send the master Adapto project a pull request for your changes

Click the Pull Request button at the top of your Adapto fork (in your GitHub account).

8. Keep an eye on the pull request and on your emails as a core developer may need to ask questions about your changes before they can accept your pull request. After your pull request has been accepted, your changes will be merged into the master codebase.