There is a huge volume of open source software available and a thriving community, however, by its very nature best practice guidance and enforcement is limited.
This guide strives to provide a set of considerations that, when applied, will benefit the community and the consumers of open source tools by aiding rigorous thinking.
It contains two lists: a set of pre-publication considerations and a checklist for software publication. As an open source document itself, comments and suggestions are welcome!
The goals of this document are to:
- Increase the quality of open source tools
- Promote a culture of clarity within the community
- Improve the success rate of published tools
- Encourage collaboration and long-term thinking
- Decrease the amount of duplicate tools
- Decrease the amount of abandonware
These steps are designed to help authors make good decisions by being aware of the available options and potential commitments.
- Consider what the goal of the software is. Once established, express that goal in as few words as possible. This will help you and others understand what the project aims to do.
- Research the market. Are there already tools which solve the same problem?
- If "yes", ask yourself what your tools will do that’s different or better than the existing ones?
- If "yes", consider contributing to one of the existing tools
- Consider how much time you can commit to the project development. This will help you determine whether you need help from other developers as well as establishing a rough project timeline.
- Consider how much time may be required to maintain it. Project maintenance can consume more time than originally expected and be quite demanding. Maintenance may be one or more of the following things:
- Bug fixes
- Managing merge requests
- Building enhancements
- Answering questions or complaints
- Promoting the tool
- Consider enlisting the help of other developers. Even if you are happy to commit the estimated time, consider involving other developers for peer reviews, support or feature development. This may provide you with fresh perspectives and new ideas.
- Consider getting financial support for your time. If the software may be valuable to an organisation or individual, it may be possible to negotiate payment. This has helped make some open source projects successful and given them a long lifespan.
- Consult with other people on any ideas or concerns you have. Aside from getting development support it can be very useful to get input and feedback from a broad range of people some of whom may be non-technical. These could be potential end-users, designers, managers or community leaders.
This is a list of suggestions to help authors make the most useful and usable tool possible.
- Documentation clearly states what the goal is
- Documentation clearly states how it might differ from the competition
- Documentation clearly states what breaking changes may have been introduced between versions
- Installation documentation is provided
- Configuration documentation is provided
- Examples of how it may be used are provided
- If relevant, a working example is provided
- Documentation acknowledges any contributors, dependencies, inspiration or references
- The software and/or its dependencies have been checked for CVEs
- Unit tests have been run and have passed
- The coverage is at a suitable level to give the author confidence in the software
- The code has been reviewed by another developer
- The code has been tested within another application
Open Source Software: Compliance Basics And Best Practices
Open Source Etiquette Guidebook
Awesome First PR Opportunities – List of awesome beginners-friendly projects with especially labelled issues. Up for grabs - List of projects which have curated tasks specifically for new contributors. First timers only - Twitter bot tweeting links to Github issues labelled with first-timers-only
- credits-cli - Find out on whose work your project is based on and if possible offer a coffee to keep them running.