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 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
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:
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:
You can check the status of local files with the command:
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"
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:
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.