Developer's guide to iPic3D in GitHub
In this quick reference guide we suppose that you already have a GitHub account (we'll call it johndoe here) and an initial understanding on how git works. This is intended as a "quick reference" so the commands are not extensively described.
Start by setting up your GitHub account in your PC:
git config --global user.name "John Doe"
git config --global user.email "[email protected]"
The main iPic3D repository is owned by the CmPA organization. Developers only have read access to this repository. To make modifications to the code you have to follow the instructions in this page.
Forking: creating a copy of the CmPA/iPic3D repository in your account: johndoe/iPic3D
To fork, go to the CmPA/iPic3D repository and click on the "Fork" button at the top right of the web page. You'll end up with a personal copy of the repository in your own GitHub Account.
Downloading the repository to your PC:
git clone https://github.com/johndoe/iPic3D
This process creates a connection between your PC and your GitHub repository. By default the connection is called origin.
To verify, the following command will list all your connections with remote repositories:
git remote -v
The main branch of the repository is called master. You can verify using the command:
git branch -a
To keep up to date with the latest modifications done by other developers, you must also create a connection between your PC repository and the CmPA/iPic3D repository (upstream):
git remote add upstream https://github.com/CmPA/iPic3D
Check again the remote connections:
git remote -v
Before making new modifications to your code, remember regularly downloading the latest version of the CmPA/iPic3D code. This process is called fetching.
To gather information about the latest version of the code from the CmPA repository type:
git fetch upstream
This command will update all the information about the upstream remote, including the modifications in each one of the available branches. Note that new local branches may be created and existing ones (like the master branch) can be pointing to a new remote location.
Always verify the branch configuration using git branch -a.
Now you can link a local branch to the remote CmPA repository. For example to link the master branch:
git branch CmPA-master upstram/master
will create the CmPA-master branch in your local directory that will track the CmPA repository. Using the same method you can link other branches together:
git branch <my-new-local-branch> upstream/<CmPA-branch-to-link-to>
were <CmPA-branch-to-link-to> must be listed after the git branch -a command.
Now merge the new branch to your master branch. First change to your master branch:
git checkout master
and then perform the merge of the desired branch:
git merge <my-new-local-branch>
You can also directly merge an upstream branch using the command:
git merge upstream/<upstream-branch>
Now is the time to make all the modifications you wanted to.
Remember that it's a good idea to use the master branch only to fetch the CmPA/iPic3D modifications and merge.
Create a new branch for each major feature that you want to add to the code:
git branch newfeature
Switch to the new branch:
git checkout newfeature
Now you can make all the modifications.
Remember that you're working in your local repository. You can commit as often as you like to this repository. In the next section we'll see how to clean the mess that developers create when doing commits. Don't worry about it right now.
Remember that you can configure your favorite text editor to work with git (here is an example for Meld).
To create a commit in you local repository use:
git commit
In the editor use the first line for the title and the following lines for the description of the modifications made. Be as clear and detailed as possible. Remember that you can also use the # symbol to point to specific issues or you can point to a given commit using the username/repository@commitHash markdown feature.
Before uploading your code to GitHub remember to:
- Download the latest version from the upstream (CmPA/iPic3D) repository.
- Merge the latest modifications.
- Cleaning your commits.
This last point is accomplished by using the rebase command.
First check your log to identify the commits that you have made:
git log or git log --pretty=oneline
Sometimes people make commits that don't work 100%. If you want to edit, squash, remove, modify the last 3 commits of your local version before uploading the code to GitHub, use the command:
git rebase -i HEAD~3
This will launch an interactive session using your text editor.
Detailed instructions on how to clean your commits are given in the following web page: Git interactive rebase
WARNING: Do not rebase any commit downloaded from the CmPA/iPic3D page. Only rebase your own commits.
Once your commit history is up to date you can now ask for your modifications to be included in the main repository.
Push (upload) your development branch into your GitHub repository:
git push origin newfeature
You could also first merge the newfeature branch with the master branch and then upload the master to GitHub:
git checkout master
git merge newfeature
git push origin master
Now go to the your web repository johndoe/iPic3D. Change to the correct branch (newfeature or master) and then click on the Pull request button.
The request is now in the hands of the manager of the CmPA/iPic3D repository. He/She may accept your new features, comment, ask for modifications or refuse your request.
The Pull request is added to the Issues list in the CmPA/iPic3D repository. While the request is still open you can push modifications of your code from your PC to your johndoe/iPic3D account, and these modifications will be added automatically to the Pull request.
