Software development is a process that can make or break your product quality. This section oulines some guidelines that can serve as input for your software development process. Smart guidelines that are transparent improves software.
Why would you use version control software and hosting (such as GitHub)?
- Easier to collaborate Version control makes it easier to work on the same code simultaneously, while everyone still has a well defined version of the software (in contrast to a google-docs or shared file system type of system). Moreover, version control hosting websites such as Github provide way to communicate in a more structed way, such as in code reviews, about commits and about issues.
- Reproducibility By using version control, you never lose previous versions of the software. This also gives you a log of changes and allows you to understand what happened.
- Backup Version control is usually pushed to an external a shared server, which immediately provides a backup.
- Integration Version control software and host makes it more easy to integrate with other software that support modern software development, such as testing (continuous integration ,automatically run tests, build documentation, check code style, integration with bug-tracker, code review infrastructure, comment on code).
It is highly recommended to start using version control on day one of the project.
A branching model describes how the project deals with different versions of the codebase, like releases and various development versions, and how to accept code contributions. Make the choice explicit in the contribution guidelines, and link to documentation on how to get started with it. Our default choice is GitHub flow branching model
GitHub flow is a very simple and sane branching model. It supports collaboration and is based on pull requests, therefore relies heavily on GitHub. The Pro Git book describes in detail the workflow of collaboration on the project with use of git branches, forks and GitHub in Contributing to a Project chapter. Other more complicated models could be used if necessary, but you should strive for simplicity.
Learning a new branching model should not stand in the way of contributions.
Use SHOULD embrace an open architecture model and way of working. This means a open code repository.
A public code repository has several benefits:
- It makes your code findable. So it can be improved by anyone.
- It shows your code to world, allowing (re)use and enables.
- It enables collaboration.
Unless code cannot be open (e.g. when working with commercial partners, or when there are competitiveness issues) it should be in a public online repository. In case the code uses data that cannot be open, an engineer should try to keep sensitive parts outside of the main codebase.
There are several ways to improve software quality and find bugs quickly and easily. By following a set of conventions, code will look 'cleaner' and be more understandable. It will also help spot syntax errors and other errors early, without having to run or compile all the time. Coding style
A coding style gives guidance on those parts of programming that are irrelevant to the compiler or interpreter. For instance, what do you call your variables? do you use spaces or tabs for indentation? Where do you put comments? .
There are open style guides for all programming languages. Choose an open standard and make clear what you use.
There are several web services that analyse code and make the quality of the code visible.
Code quality analysis services are web applications which have the following features:
- Automatically analyse your code after a Github push
- Usually free for open source projects
- Most supports multiple programming languages, but not every language will have the same level of features
- Grade or score for the quality of all of the code in the repository
- List of issues with the code, grouped by severity
- Drill down to location of issue
- Default list of checks which the service provider finds the best practice
- Can be configured to make the list of checks more strict or relaxed
- Can be configured to ignore files or extensions
- Can read configuration file from repository
- Tracks issues over time and send alerts when quality deteriorates
- Optionally reports on code coverage generated by a CI build
Releases are a way to mark or point to a particular milestone in software development. This is useful for users and collaborators, e.g. I found a bug running version x. For publications that refer to software, refering to a specific release enhances the reproducability.
Apache foundation describes their release policy.
Release cycles will depend on the project specifics, but in general we encourage quick agile development: release early and often Semantic versioning.
Releases are identified by a version number. Semantic Versioning (semver.org) is the most accepted and used way to add numbers to software versions. It is a way of communicating impact of changes in the software on users.
A version number consists of three numbers: major, minor, and patch, separated by a dot: 2.0.0. After some changes to the code, you would do a new release, and increment the version number. Increment the:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- PATCH version when you make backwards-compatible bug fixes.
APIs are important and good API design guides help you.
- An open HTTP API guide can be found on: https://geemus.gitbooks.io/http-api-design/content/en/
- Microsoft REST API Guidelines: https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md