House Rules

All source code must be under revision control.

This includes application code, web pages etc, but also include minor configuration files such as apache settings, deployment scripts, cron jobs etc. The requirement is that the working product can be re-established on a new system entirely from the repository onto a documented standard platform.

Revision control commit processes are followed so that changes accepted into the system have been peer reviewed, pass the test suite and are clearly associated with a Jira Issue (story or bug)

Goal

The goal of the revision control system is to be able to obtain the complete set of files required to reproduce a system or application for any release or development version.

Ideally the only step required to get started is a single checkout from the trunk. All dependencies dragged in by the build scripts.

Justification

1. Software is a living document it undergoes fairly frequent changes and is often worked upon by different authors. Revision control allows changes to be tracked against time, branches and merges to be performed and allows revert to a previous version if a change is found to be defective. Revision Control also allows the code used to produce any version of the software to be regenerated.
2. An application is not just a few source code files, often to build a deployed working system a variety of different source code, images and system files may be changed. If these are left out of the RCS then it becomes difficult to reproduce the actually running system. Hence the repository should also include scripts, config files, how to documents etc.
3. As an Open Source project this is even more important. We need those working to fix bugs, add tests and add new features to the project to be able to find all the components required to code, build and run tests.

Recommendations

All source code is placed in a project in the Voluntari.ly Github organisation repository. https://github.com/voluntarily

All projects must have a Readme identifying the purpose of the repository, which component it relates to, links to documentation pages here and build information.

We use Trunk based development

Read and follow this: https://trunkbaseddevelopment.com/

Open Source

All source code is provided with an open source license - unless required for other reasons our default licence is the Mozilla Public License (MPL): https://www.mozilla.org/en-US/MPL/

Do not include in the project any dependencies or libraries that are not compatible with this license.

Document the development environment and build process

List any development tools required to build, test and deploy the project.

The important thing is that it is clear from easily available documentation what a new developer has to do to get, build, run, test and debug the project.

Test coverage

Each project must contain unit, functional and UI tests that allow regressions to be caught.  A regression is when a change breaks some existing correct behavior. The test suite represents the functional specification of the system.

Voluntari.ly prefer to use a Test first development model:

For new features, modules etc:

• generate a code skeleton little or no functionality
• generate the test suite to cover the module
• create test functions - which should fail due to missing functionality
• Write the code.
• When the tests pass stop.

For Bugs and defects:

By definition a bug in the code base is also a bug in the test suite which should have caught the bug.

• Create or update a test to demonstrate the bug
• Test should fail
• Change the code
  
• test should pass

A pass of the test suite on the working branch is required before pull request to the main branch of the repository will be accepted.

A pass of the test suite on the release branch is required before deployment to production or staging can proceed.

An automated test machine should note changes to the repository, checkout the new code, build it and run the tests. if these pass the automated test can mark the revision as a 'known good' if the test fails the committer should be informed. This should happen within a couple of hours of the commit to facilitate continuous integration.

There is a deployment system to deploy the working code to test and production servers.

1. For web hosted services the deployment system should provide the ability to move the application marked as a tagged revision in the code repository to a service host.  This may include deploying multiple subsystems and possibly third party tools and modules.  The deployment script is a resource that should also be under revision control.
2. For Client hosted applications the deployment system should be an installer appropriate to the target operating system.  Deployment will consist of building the application and installer package based on a revision control tag, moving the package to a download site along with version information and issue tracking information in the form of release notes.  it should be possible to reproduce a release should the package be lost.

During deployment and maintenance any affected web servers or services should produce appropriate feedback to affected users: e.g. Under maintenance, Please try again in <x> minutes. - unless continuous deployment is implemented using multiple servers.

The system is documented

1. End user documentation which should give information about the use and requirements for the system. For web services this will be in the form of associated web pages. This documentation must be up to date with the current supported release and accurate. The goal of this documentation is that users are able to use the system effectively.
2. Internal project documentation which should include information about the project, its requirements, technical solutions, System architecture, releases, server and deployment information and so on.  The goal of this documentation is that an unfamiliar developer can find out what it required in order to maintain the system effectively.

There is an issue tracking and a documented change control process

Main Agile development method is Kanban.

Critical issues will be prioritised in the queue and should be completed first.

All issues however will enter our system through Jira and be filtered and prioritised by the Product team.

All changes to the code base should be associated with a matching Jira ticket - bug or feature.

The system is able to be monitored at run time.

By default the system should generate a low level of log messages to indicate normal operation and to flag exceptions. When necessary the system should be switchable to generate higher levels of logging including debug and trace messages. Such messages should be compatible with cloud system monitoring systems.

The system should alert the sysops if an important exception occurs or the system stops working.

Where the system includes a process moving information from a number of feeds, through batch processing and to some repository these production steps should be monitored and exceptions reported.

There is a technical support plan in place

A reporting and escalation hierarchy should be in place that alerts sysops to immediate issues and allows them to contact key developers for help.

Users and Access levels are identified

Users fall into the following roles.

• Volunteer
• Opportunity Provider
• Activity Provider
• Engineering
• Support
• Operations
• Administration

Each project should identify the users involved and specify the level of access or restriction required. 

Data is managed

Persistant data generated by the system is:

• Stored securely - cannot be read, modified or removed by third parties
• Privacy is maintained for user personal information.
• Access security model to be defined. All data should have a clear owner/manager.
• The DB has a data integrity policy. This includes backup requirements, mirroring or replication requirements and disaster recovery.