This is step 3 in your journey toward rock-solid scientific Python code.
So your code is under version control and it’s floating up there in the cloud. In principle, someone else could use it. But how will they know it’s there? How will they know what it does, and how to install and use it?
A README is minimalist documentation – just what is absolutely necessary for someone to start using your code. Most often, that someone is your future self, who has forgotten things. Here’s what to do:
Note: it’s also possible (and even easier) to add a README directly on Github, by clicking that nice green button:
Nice work! Now others (or your future self) stand a decent chance of being able to use your code. But they may not want to use it in exactly the same way you do. In fact, there’s a good chance they may want to modify it, or incorporate it into some other code they have. By default, copyright laws don’t allow them to do that. If you want others to be able to use your code for their purposes…
This part is fairly painless because, unlike a README, the license you use should NOT generally be customized for your project. It’s much better to choose a standard license, so that other people don’t need to agonize over all the fine print. The most common licenses for open source scientific software are
All of these allow others to use, redistribute, and modify your code. The GPL license imposes one restriction that is absent from the others: other code that uses yours must also be GPL. Some view this as a great way to encourage more free, open-source code. Others view it as an impediment to your code being used. My suggestion is to use a BSD license, but if you want to investigate in more detail, try Choose A License or go read this paper.
Here’s what to do:
That’s it! Other folks can now legally adapt your code for their own purposes.
Congratulations on making it this far. Now go to step four.
It’s great that other people can now make improvements to your code. It would be even better if they sent those improvements back to you! To encourage that, you should add a Contributing.md file to tell them what your standards for acceptable code are and what the process is for adding code to your repository. Github provides a standard template for such a file, though for small projects you can provide something much simpler. Some good examples of contributing files are:
If people have contributed to your project, it’s standard to have a file called Thanks.md that lists their names and contributions.