This page aims to describe the development process/philosophy that should be used when developing software for the UKRR. The assumption here is that the code is developed using python as the majority of the code developed in the registry is python based. The same principles should be followed for other code bases such as UI code in Anglular etc.
Software development falls into two categories:
- Enhancement/Bug fixes of current code base
- New Software
In both cases the code should be part of a repository managed using git. Typically the code should be stored in the https://bitbucket.renalregistry.nhs.uk repository. All code should be formatted using black (https://github.com/psf/black) it is recommended that this be done as a pre-save function in the preferred code editor vscode (https://code.visualstudio.com/) or a git pre-commit hook.
Development of code should be done using branches (where ever possible) and pull requests which should be reviewed by at least two developers before merging in. If an issue is identified in the code it needs fixing not ignoring and a ticket raised before merging and deploying.
Changes to code should always be supported with tests especially if they are bug fixes. One of the reasons for this is due to the history of some of the code bases it is difficult to tell if a fix has broken some other dependency so by ensuring the right tests are in place future changes hopefully will not break earlier code.
All new code should be supported with an adequate set of tests with new tests added as issues are identified to prevent future re-occurrences. Common issues in the current code are caused by ignoring exceptions and none variables. Errors need to be handled and not just ignored. Variables need to be checked they exist and not just assumed they will be present. Given the wide variety of sources we receive data from assuming the data supplied is correct is never good. Trimming spaces and handling text when a number is expected are common issues.
All code needs to be adequately tested prior to releasing to others for testing. For the UKRDC this means the developer should test the code they develop and ensure it is working as they expect then deploy to the dev server and test with some sample dataflows. Once this has been proven successful the code should be deployed to staging where a wide range of real files can be tested and wider testing done before finally releasing to live.
All code changes should be reviewed by at least two other developers before being merged in to the master branch. Typically this would be done with pull requests.
Ideally all code should be added to the CI engine Bamboo (https://www.atlassian.com/software/bamboo) and deployments set up as appropriate. Due to the way the engine can work it is important to review the logs for errors as sometimes errors do not cause a build failure. This may indicate the build process needs tweaking.
Deployment of code needs to be considered and appropriate assist script s should be included in the code base as required.
All code should be documented and should describe not only how the software should be used and deployed abut also some architectural guidance to assist someone looking at the code for the first time to understand what the code is trying to do and how it is trying to do it. Background as to how the code fits into a bigger system or why the code is required is also helpful. The aim of the documentation is to provide the information required for someone to update/correct/further develop the code as quickly and easily as possible.