[«PREVIOUS: More advanced things to think about»] - [Table of Contents] - [NEXT: How to start contributing to open source»]
What makes an open source project good and useful?
Open source your own project (or tune up a project that’s already open):
- If you only have a few lines of code, maybe a git Gist or somewhere else like CodeOcean might be easier than a git repo.
- Avoid jargon, or at least expand it into plain english if possible. Challenge: Can you explain your project using only the ten hundred most used words?
- Readme files. Create a README.md file to explain what your project is, how it is used, and how to contribute and report bugs. readme.md is the file that is automatically displayed when you open a GitHub repo.
- Roadmap - a roadmap file allows others to see what you have planned in the future, and helps you to set priorities.
- Contributing guide - make a file called CONTRIBUTING.md and guidelines for contributors so they know what they should do if they want to help you out.
- Issues - use GitHub issues to record your bugs and planned new features. GitHub tags can make it easy to sort the issues.
- Code of Conduct! - good projects have codes of conduct to make sure that people are treated well, and state how violations will be handled. Github has an Code of Conduct wizard to make it easy to add one.
- You’ve been creating scientific software, so you deserve some credit! Add citation guidelines to a recent/relevant paper if you have one. You can also add a cff (citation file format) file, or get a DOI for your repo using Zenodo.
(This list was largely inspired by Mozilla’s open leadership 101.)
Licencing
There are lots of open source licences out there. Most are pretty good. Use one! Some allow users of the code to do anything they like with their code - these are known as permissive licences. Examples are the MIT Licence or Apache.
Here are some ways to help you choose:
- https://choosealicense.com/ - does what it says on the tin and helps you choose a licence.
- https://tldrlegal.com/ - plain english explanations of licences in bullet form.
[«PREVIOUS: More advanced things to think about»] - [Table of Contents] - [NEXT: How to start contributing to open source»]