The "how to contribute to aMSN2" thread

[drf]

Hello everyone,

with aMSN2 gaining more popularity, hence more people looking forward to contribute, we have an increasing number of incoming patches and people contributing. Since we're using git now, we have already a great system to track contribution, so if you want to help or send a patch, we are using from now on github's pull request system. If you're already familiar with it , just go ahead and start developing, you don't need to know anything more than our main branch address, which stays the same:

http://github.com/amsn/amsn2/tree/master

If you're not, here comes a small tutorial for you.

 1 - Go to the address above. You'll see a button, "fork". Hit it. This will fork our repository and create your own copy of it on your account. Now you have already your own aMSN2 repository where you will be able to develop.

 2 - Write code, push changes to your forked repository, and so on... well, do your thing!

 3 - Once you're satisfied, and you think your code is ready to be merged with the main branch, you have a nice button, "Pull Request". Hit it, it will send me a message notifying that you want to push some code to our repo.

 4 - The patch will be reviewed and applied to trunk. Obviously, all commit history & authors will be kept intact.

See how easy it is? The last missing bit is to keep your forked repo up-to-date with the master branch. It is pretty easy, here comes the steps you need to do:

 1 - Add a new branch to your local repository. To do so, browse in a terminal to your local copy and hit those commands:

Code:

$ git remote add -f amsn git://github.com/amsn/amsn2.git
$ git checkout -b amsn/master

You need to do this only once.

 2 - Now, everytime you want to sync your local copy, just do this:

Code:

$ git pull amsn master

And the main branch will be merged with your local copy. Easy, isn't it? You also probably want to push after this.

I hope you enjoyed this little tutorial, add questions/remarks/anything here below. I am looking forward to receive your pull requests!

[billiob]

Feel free to come to our IRC channel (#amsn@freenode) to ask questions about the code.

[billiob]

Important mails :
http://thread.gmane.org/gmane.network.instant-messaging.amsn.devel/9497
http://thread.gmane.org/gmane.network.instant-messaging.amsn.devel/9502
http://article.gmane.org/gmane.network.instant-messaging.amsn.devel/9796

[kjir]

Hi everyone,

I wanted to add something to the tutorial since on my branch I added papyon as a git submodule. On my branch I will be working mainly on the ncurses front-end, so if you want to help on it maybe you should watch my branch too. Here are the instructions:

First, clone the repository, possibly your own fork, otherwise my public branch (you won't be able to commit in this case, though!)

Code:

$ git clone git://github.com/Kjir/amsn2.git

After that you'll have to initialize and pull the submodules. This can be done in one command:

Code:

$ git submodule update --init

Please notice that with submodules development works a little differently, because the superproject (that is the main amsn2 project) will reference a specific revision of the submodule and it will not automatically point to the latest commit on the branch. I guess this was thought to give the developers a stable base version of a submodule to rely on, only updating the references when necessary. To understand better what I am talking about and to undestand the workflow please refer to http://git.or.cz/gitwiki/GitSubmoduleTutorial

In short, to make changes to papyon you have to fork and check out the papyon repository in another directory and work on it there. If you want to use your changes in your amsn2 repository you'll need to update the references there.

To update the references (I strongly advise you to read the aforementioned tutorial) you would do this:

Code:

$ cd /path/to/amsn2/papyon
$ #eventually git pull changes from remote branch
$ git checkout master
$ cd ..
$ git add papyon #no trailing slash!!! THIS IS IMPORTANT
$ git commit -m 'Updated papyon reference to latest commit'
$ #eventually git push your changes to your remote branch

This is it, it takes a little training, but once you understand the concept it's not hard to adapt to it

EDIT: Updated instructions to reflect the name change

[wagner]

I have  some questions!
After I've forked the repository, how can I:

- Do a checkout from the forked repository.
- Do a commit.

I think these are the only commands I'll ever need.
thanks!

[kjir]

If you don't know how to use git, read the guides on github, they explain everything you need to know...

[billiob]

the repository is now hosted at http://github.com/amsn/amsn2/