So you have written some software and want to release it to the world! Congratulations!
You’re not done yet. Now you need to document your software and make a release so that everyone knows how to use it. Here are the minimal set of files that you should include and a discussion about each.
These are the minimal set of files you should include in your software. I have included .md extensions for files that are usually markdown.
Your software must include a file called VERSION that describes the current version. When you make an update to the software, increment the version number. Usually software developers use a major version (e.g. 1.0, 2.0, 3.0) to indicate major changes to the software and a minor version (e.g. 1.1, 1.2, 1.3) to indicate incremental updates. If there is a really minor change, you might use an additional layer, (e.g. 1.1.1, 1.1.2, 1.1.3). Don’t go beyond three layers, and don’t do like some people do and add X and then XX (like this).
Your code should also include a -v or –version flag that prints the current version of the software. I usually have that code read the VERSION file and output the file contents.
You should include a CITATION.md file that includes at least the title of your paper, but hopefully includes a link to the actual paper(s). Make it easy for people to figure out how to cite your work, and they will. Hide it and make it difficult, and they won’t cite you, they’ll cite some random paper by your competitors!
You need to describe:
- The dependencies for your software and where to get the code.
- How to install your software (make, Build.PL, setup.py) etc.
- How to test that your software has built correctly
- Any known issues or work arounds with your software.
In github this is the page that appears under your code base, and it should introduce your code, what problem it solves, and link to the installation page (above) so that people can quickly see how to install and test your code.
You should include a brief description of how to test your code. Your description should say how to test it and what to do if the code does not pass the tests.
Your code should have a LICENSE file so that people know how it is licensed. Usually we use either the GPL or the MIT license. I slightly prefer the MIT license because it is simple, requires people to acknowledge our work, and we are not liable. There is more information about software licenses available at choosealicense.com
You should include a changes file that lists changes since the last update. Note that the CHANGES.md file should not contain a list of the diffs, that is why we have versioning. It should contain notes about why the changes were made or the issues they resolved, potentially with links back to bugs or issues reported in github. This is probably the file that is forgotten the most, and updated the least.
Community Guidelines
In addition to these files, your software should also include Community Guidelines. In particular, you should consider adding:
- A code of conduct: how do you expect people working on your software to interact?
- Contributing Guidelines that suggest how people can make changes and edits.
- Templates for Issues and Pull Requests
Buttons
Everyone loves buttons, and you can have both buttons created by tools and your own buttons. Here are some examples you can add to your README.md
[](https://edwards.sdsu.edu/research)
[](https://www.zenodo.org/badge/latestdoi/60999054)
[](https://opensource.org/licenses/MIT)
[](https://travis-ci.org/linsalrob/PhiSpy)
[](https://pypi.org/project/PhiSpy/)
[](https://anaconda.org/bioconda/phispy)
[](https://anaconda.org/bioconda/phispy)
[](https://conda.anaconda.org/bioconda)
You can see what those look like on the PhiSpy repository