The CCP-WSI Clearing House

To pass the CCP-WSI Clearing House each of these contributions should satisfy a number of elements, each of which are described in the sections below. Please note that each aspect of the CCP-WSI Clearing House is documented fully on the Git repository project wiki on GitHub. We have included links to these pages where relevant but only members of the repository will be able to access these. To join the repository please create a GitHub account and send us your username, selecting “Access CCP-WSI Code Repository” from the Category drop-down menu on the Contact Us/Join Us page.

Version Controlled Repository

All contributions must be to the Git repository.

Version control is the most fundamental of software engineering practices and is essential in the development of good quality code both for individual developers and when multiple collaborators contribute to the same repository as with CCP-WSI. The CCP-WSI Code Repository uses Git as its choice of version control software and the repository itself is privately hosted by GitHub. For any potential contributors who are not already familiar with version control in general and Git in particular, CCP-WSI run training courses for complete beginners in Git as well as offering training on following the development process and contributing to the repository over all. There is also a wealth of information available online, we recommend Software Carpentry

Rules and Guidelines

We ask that all contributors familiarise themselves with the CCP-WSI Rules and Guidelines before writing any code. These include:

• Naming conventions (for features and feature branches)
• Using the correct directory structure
• Ensuring essential files are present

These are documented fully on the GitHub wiki with the code repository and great care has been taken to find an appropriate balance between putting in enough rules and guidelines to ensure good quality software without making the process too cumbersome for the individual developers. We welcome feedback on all aspects of the CCP-WSI Clearing House and are open to suggestions from contributors.

The Development Process

Contributors must follow the CCP-WSI Development Process which is a git workflow, adapted to best suit the needs of the CCP-WSI Code Repository. It is fully documented on the Code Repository wiki and training events occur in addition for new users/contributors. The process is explored further below.

Creating a new feature branch from the dev branch

This is standard practice in a Git workflow and has been found to be very effective whilst incurring minimum overhead.

Developing Code

Following the Rules and Guidelines as introduced in the section above.

Documentation

It is vital that all contributions are sufficiently documented so they can be used and extended further. We understand, however that this can be time consuming and often developers have less motivation for this part of the development process! Therefore all we ask is for contributors to include one “README” file for which we provide a template. This ensures that all essential documentation is included and as all contributions are documented in the same format and style it makes the software much more usable and easy to understand for new as well as existing users of the repository. Contributions to the Code Repository will not be accepted without this file present and complete and manual checked are made on this. We provide an example of a complete README file in addition to the template itself to aid in the completion of it.

Anvil

Anvil is a continuous integration software testing service, using the open source software Jenkins. Continuous Integration is the practice of regularly merging code, which is then verified by an automated build of the software. This way any issues are found quickly and can be fixed before becoming potentially worse and it ensures software builds and runs on independent operating systems. This is of fundamental importance to any project hoping to release and distribute their software and is a key element of the CCP-WSI Clearing House.

Builds for an contributor’s feature branch are performed as soon as commits are pushed to GitHub. New features branches are automatically added and built the first time they are pushed. The development and master branches also auto build when commits are made but this is expected to be less frequent; they also take longer to build as they must build for each version of OpenFOAM. Tutorials are also run on a regular base to further test the software. In addition to this we have various tests in place which automatically check adherence to some of the rules and guidelines. If any if these tests fail, the build will fail.

Contributors are instructed to check that their feature branch is successfully tested on Anvil before submitting a “pull request” to merge their work into the main development area.

Pull Requests

When a feature is complete and the contributor is ready for this code to be merged into the main development area they, in accordance with standard practice, must submit a pull request. Only members of the CCP-WSI Code Repository admin team are able to approve pull requests and there are a number of manual checks they perform first, to ensure the contribution is of the required standard and quality. These include:

• Check the science is relevant and suitable for the CCP-WSI Code Repository
• Check the feature branch build passes on Anvil
• Check the ReadMe file is present and complete

When a pull request is approved the feature is added to the Code Repository Table of Contents included with the repository enabling users to easily browse the software and documentation.

Summary

The CCP-WSI Clearing House exists to ensure that the CCP-WSI Code Repository contains good quality and well engineered software which is relatively easy to use and extend further. We depend on our contributors following our rules and processes but also welcome feedback on each aspect of the Clearing House.