Source Code Management Interest Group Tools and procedures used in the yacs project

PreviousNextIndex

How to contribute to yacs core software?

A bird-eye view of the workflow supported at Github

Alexis has referenced various best practices, and he has driven some of us to practical usage of Github. This page is a compact digest of things that we have learnt throughout the process, and that you can use for yourself.



 

So, at the beginning of our story, you are Alice, a developer willing to contribute to the yacs project.

You have a Github account, don't you?

In theory you could do it without github. In practice, github is providing a fantastic service, and we will assume that you have created an account for yourself, with an id that is specific to you.

In this document, we will refer to your account id as alice. But of course, your account will have a different value, and this is the one to use in commands provided below. If your account has the id joe_foo, replace alice with joe_foo in all examples below.

Fork the project for yourself

Go to the github site, authenticate if not done yet, and use the interface to fork the project yacs/yacs.

If you preserve the original name yacs, this will create a repository alice/yacs just for you. It will stay connected to the upstream repository used by the community, to manage updates, branches, etc. And at the same time, it allows you to consider any change you would like to implement in yacs. Really. Any change.

Copy your repository to your computer

Create a directory to host files from your repository. From this directory, type the command that will download all files from your repository, something like:

git clonegit@github.com:alice/yacs.git

This command will also preserve the link to the repository, and this explains why it is so easy to synchronize your computer with the repository hosted by github. We will see this in a minute.

Connect local files to the original project too

You have forked the yacs project for yourself, but it is easy to understand that you will have to synchronize your files with the original project from time to time. Type the following command to add another source of reference files:

git remote add upstream git://github.com/yacs/yacs.git

Each time you will use the name upstream this will refer to the main yacs/yacs repository. We will see later in this document how to integrate upstream evolutions into your own code.

Synchronize your computer before you code

Of course, you don't need to do this just after the clone command. But let's assume that some time has passed by after the initial installation on your computer, and that you are about to provide a significant contribution to the code. The best practice is to ensure that files on your computer are fully aligned with your repository, with the following command:

git pull

You can check the status of local files with the command:

git status

Providing that the two commands report a normal situation, you are safe to edit files, delete, add or change code, as you wish.

Consolidate changes to your repository

After any significant change you may wish to upload changes to your repository at github. The commands to use are really simple:

git commit -am "describe the change here"
git push

After a successful push, you can even consider to delete local files, and to clone your repository at another machine if you wish.

Ask for integration into yacs core code

When you will be proud enough of your achievement, you may want to offer your code to the yacs project. Visit your repository at github and hit the "pull request" button, by which your code would be pulled from your own repository and integrated back to the yacs/yacs repository. Integrators of the yacs project will review proposed changes and take them into account -- or not, eventually.

Integrate evolution of the yacs project into your repository

When you have been notified of the successful integration of your contribution into yacs core code, or before considering some major development, you may wish to resynchronize your repository with yacs/yacs. This is done by integrating all changes at your computer, and by pushing everything back to your repository.

You have to be sure that all local changes have been commited, then type:

git fetch upstream
git merge upstream/master

If the last command is reporting some conflicts, you have to edit files and to delete unwanted code manually. Then commit changes to clear merging issues with the command git commit -am "manual fix of merge conflicts" or similar.

Last but not least, you have to push all changes back to your repository:

git push

Overall information flows

As depicted in the image below, there is one loop managed directly by Alice, centered on her repository hosted at Github. And there is another loop managed by integrators of the yacs project.

PreviousNextIndex