Sunday, November 15. 2015
Useful links and commands when collaborating in GitHub
During the last months I have been collaborating with OpenSC in order to properly manage Spanish ID card (DNIe). For that reason I have worked several times with the OpenSC repository in GitHub (cloning, changing, updating, creating a branch and submitting a pull request). Although it is not very difficult and very well documented in the collaboration site, I wanted to summarize the process in my blog. This entry explains the list of steps to submit a change in any GitHub project (although it will specifically use OpenSC as an example).
Cloning the repo
The first step is forking the project repository in your own one. This step is done using the GitHub page. Go to the original project (OpenSC in my case) and click the fork button. It is as easy as that, after forking you have the OpenSC project listed in your own projects.
After that you can clone your own fork as it was any of your projects.
git clone https://github.com/rickyepoderi/OpenSC.git
But, because it is a fork of another project, the original OpenSC link should also be added as a upstream.
git remote add upstream https://github.com/OpenSC/OpenSC.git
This way, your local copy has two remote urls, your own original fork and the remote upstream from OpenSC.
git remote -v origin https://github.com/rickyepoderi/OpenSC.git (fetch) origin https://github.com/rickyepoderi/OpenSC.git (push) upstream https://github.com/rickyepoderi/OpenSC.git (fetch) upstream https://github.com/rickyepoderi/OpenSC.git (push)
Making the changes
At this point a new branch can be added to your local repo and you can add all the changes you need.
git branch dnie-issue-xxx git checkout dnie-issue-xxx
In the new branch your changes should be performed and tested. The changes are committed to a new branch in your GitHub. In my case (OpenSC project) I needed to bootstrap and configure the software.
./bootstrap ./configure --with-pcsc-provider=/home/ricky/apps/opensc/lib/libpcsclite.so --prefix=/home/ricky/apps/opensc PCSC_CFLAGS=-I/home/ricky/apps/opensc/include/PCSC --enable-dnie-ui
In the case of DNIe there is a special option --enable-dnie-ui which enables a confirm message before a real signature operation is executed with the card. This behavior is inherited from official DNie driver implementation (I suppose that previous OpenDNIe developers maintained the same behavior than the governmental implementation). This option can be omitted if you do not want to received that extra confirmation.
Now you can make your changes in the code. Whenever you want to save to your local repository or to your GitHub a typical commit is executed and pushed to your origin.
git commit -a git push origin dnie-issue-xxx
I am going to summarize the tests I usually do to check that DNIe is working properly:
Using the DNIe test page. The current steps I usually perform are the following.
Start firefox and go to the URL. Login is required to access the card and finally a summary page with information of your certificate is displayed.
Click in the link Pulse para acceder a la aplicaciĆ³n de firma at the bottom to access the signature test page. Here a Java applet (it does not work in chrome) is started and a signature is performed.
After checking the signature works go back in the browser and reload the first summary page. (Now this step does not work because a problem with DNIe and OpenSC. We are working on it.)
Configuring thunderbird and testing a signed mail. I usually send a mail to myself just signing it.
Perform a signature using the pkcs11-tool command of the OpenSC bundle. The command is not very complicated:
List the objects in your card:
./pkcs11-tool -l -O ... Private Key Object; RSA label: KprivFirmaDigital ID: XXXXXXXXXXXXXX Usage: sign, non-repudiation Certificate Object, type = X.509 cert label: CertFirmaDigital ID: XXXXXXXXXXXXXX ...
With the ID of the the signing key perform a sample signature (it requests the pin and a sample text to sign):
./pkcs11-tool -d XXXXXXXXXXXXXX -s
Once you think your code is ready and it is good enough it is time to commit all your changes and submit a pull requests to the upstream project (OpenSC in my case).
Submitting a pull request
Again this process just needs GitHub access and your fork branch ready with the changes. Just go to your branch and click Pull Request button. This starts the process to submit a pull requests to the original project. You can follow GitHub instructions about submitting a pull request although the process is quite simple.
Syncing to uptream
Usually (as it was explained before) your changes go to a specified branch that then is submitted using a pull request. The master branch can be updated with upstream (with the upstream OpenSC project) in order to start a second modification. This way you need to sync your master branch with the current state of the upstream project. The syncing process is explained in the GitHub documentation as well.
Change to master branch:
git checkout master
Fetch the changes from the upstream project:
git fetch upstream
Merge upstream and your local changes:
git merge upstream/master
I usually create branches to implement my changes or fixes, so the master branch has no local modifications and the merge goes smoothly. Nevertheless the merge process maintains your changes if they exist. Now your master branch is again up to date with the upstream project.
This time the entry is a little summary of the typical git commands that are used when collaborating with a GitHub hosted project. As usual the entry is mainly for my own use (I prefer to have my personal sheet pointing to the official pages). The next time I will have to work with OpenSC (or any other project hosted in GitHub) I have my steps here for a quick access.
Regards!
Comments