When looking at a well developed project on github I often find myself impressed and surprised with how many integrated utilities can be applied to a project. Each adds their own flavour and functionality, while leaving a small footprint within the project. Taming the extra utilities often seems daunting to newcomers but as it turns out setting up a healthy, intelligent, and test driven github repository is much easier than one would imagine!
~
README & .GITIGNORE
One thing I’ve come to appreciate lately are well laid out, and informative READMEs. It’s often the first thing a user will look at when viewing a project and acts as the metaphorical doormat.
A README’s goals are to;
- describe the project, its scope, and its general outline
- provide steps to locally recreate the project
- illustrate how to perform the testing functions
- define how others can, if at all, participate with the project
Luckily much of this is done for us and requires minimal setup!
- In the root of your project, create a file with the name
README.md
- Using your favourite editor add each needed part from above. psst.. don’t know what to include? others have created templates that we can use, you can check the one I use here.
That’s it! A beautiful README. Having a welcome mat is a nice touch isn’t it?
~ & ~
Unlike README’s .gitignore’s intend to hide pieces of the local project. While merging a local .git repository to a upstream remote, the .git service looks for a .gitignore file in the project root, then using filename recognition it chooses what to push to the remote. This saves the programmer the headache of sorting out what files / folders should be applied to a commit.
A .gitignore’s goals are to;
- identify which files / folders are to be ignored when merging local repositories with upstream remotes
The steps are just as simple;
- Create a file called .gitignore
- Using your favourite editor, add it to the files and folders you wish to have ignored when you push your commits. Like the README we can take advantage of others hard work (though acknowledgment of work is important) by using templates provided online. Personally, I recommend githubs.
~
Licenses
I’m not a lawyer. I’ll start with that and have it over with, much like my professor who told us the exact same thing, I cannot and should not be asked to provide any sort of legal advice.
Moving on, including a license may not seem important but it actually is. No respectable user base will touch your code if it does not contain one. Furthermore, it provides potential contributors a chance to understand your vision for the project.
The goals of a License are;
- To provide protection against potential legal action that would be taken against you for your open source projects use
- To add legal legitimacy to your work
However, before anything else it is important to understand the potential licenses that can be used. To assist, here are a few of the common ones used in open source;
You’ll notice on the left most side that each license has requirements that the holder of the license must fulfill, make note of these.
The steps to add a license to your github repository are;
- Create a file with the name LICENSE
- Using your favourite editor, include the required text for the license you’ve selected, making sure to edit the necessary parts as required.
After that you’ll notice that while on github.com clicking on your newly uploaded LICENSE file will open a summary of your license, similar to the links above.
~
Continuous Integration
As we begin to understand how to more efficiently and quickly create projects of varying sizes, we also begin to recognize the need for some form of standard automated testing. A short time ago it would have sufficed to have a single, or small group, of people maintain their source code’s health by managing the various testing, branching and merging needs, however, because of the complex nature we see what many projects evolve into, this is no longer the case. Automated CI’s services offer a passive set of eyes to be ever vigilant on a project, not eliminating the need for programmers to be mindful but increasing the potential for issues to be caught earlier.
As with the above, most of this is done for us again, as a few open source projects provide exactly what we are looking for, which is cloud space and automated testing. I recommend using TravisCI. As of the day of writing this, TravisCI is free to use with all open source projects.
You can check TravisCI out here.
The steps for adding TravisCI are explained best on their site.
However the steps are;
- On the travisCI site grant access to a repository you wish to integrate
- Add a
.travis.yaml
file to your project- This file is the blueprint to a project, the travisCI agent uses it to create a virtual instance of the project, then runs included tests
- travisCI is also shown in github, you’ll notice once added all of your previous commits will begin building
- trigger the travisCI by making a push
Provided below is a example of a travisCI.yml I created for a project that I was working on recently.
This project was using Django and python’s unittest library.
~
So that’s it, those are the basics of creating a healthy, intelligent, test driven github repository. It doesn’t take long to complete and it adds a layer of professionalism that isn’t overlooked by interested contributors.