IATI Code Checklist¶
Our code checklist is based on a set of principles that provide a framework against which code projects can be measured.
It may help to read each item as a question (that we should know the answer to).
E.g. Is this ‘our’ code? Is it on our server? Does it have a licence? etc.
The creation of this checklist allows us to:
- communicate with new team members, external contractors, and other developers, about the way we do things.
- allows us to audit current projects to find and fix gaps.
- allows us to test new work against the framework to make sure all the bases are covered.
Each code repository in our GitHub account should have a CHECKLIST.rst file
We should know which code is ‘ours’¶
Generally IATI Code can be found here: https://github.com/IATI
There may be rare instances of code that have yet to make it into the GitHub organisation account, but it is our desire and intention for all IATI code to be there.
All code should have a lead person identified¶
This makes it easy for others to work out who they might need to talk to.
Our projects/code should be appropriately branded.¶
This has been an issue for IATI as it has developed.
Each piece of code should have a document, a roadmap, and estimate of resources, and a licence.¶
Generally we’re probably using a open source or free software compatible licence.
There will usually be discussion as to whether or not we use a permissive or copyleft licence.
We should be confident that updates to our code will not break existing functionality¶
Deployment of new features, especially in feature rich environments, or of new website configurations has the potential to mess up existing data, layouts, functionality.
Writing tests is one way of checking that large application are still doing what they are supposed to be doing.
Does this mean everything should have a suite of tests? Probably!
It should make sense in the way people access our tools/code¶
Essentially the domains we use to host applications should make sense.
Code should be kept in one place e.g. GitHub organisation
Our code should be on our servers¶
As opposed to, for example, a developers personal server.
We should be able to monitor the performance of those servers
We should be able to monitor the performance of the software
Status of the software should be indicated in the deployments¶
For example, much of our code is deployed on development servers. Some of it is actively shared (i.e. we email people links, talk about it openly), other stuff is thrown up for testing, but may still be discoverable. It should be clear to visitors as to the status of that software (e.g. they are using a development version of the software). Moreover, we may be deploying software/service that are considered pre-Alpha, Alpha, Beta, properly stable etc..
We should know how our code is being used - logs!¶
Are we gathering and making use of:
- server analytics
- google analytics
- built in loggers
Our code will need to adapt with schema changes and changes to external systems upon which it relies¶
If, for example, the datastore, or the registry change then our code should also change
When creating code these dependencies should factored into the design and upkeep of the software.
Developers should be able to find useful resources and help easily¶
Developers within the existing team, externally and for anyone that joins the team.
Each project should clearly describe how other developers can get involved¶
Each repository in GitHub should have a CONTRIBUTING.rst document
We should be able to communicate with the users of our code.¶
This could be by:
- technical blog
Users should be able to communicate with us about our code¶
There should be pathways for
- technical users/queries
- non-technical users/queries
We should protect our users privacy¶
- good password security
- delete data that we don’t need to keep
We should be clear about how we work with contractors¶
- systems we use
If our code works with IATI data, have we considered how it will work as the IATI datasets grow, both in terms of individual file size and as a corpus¶
We should be aware that it is hard to estimate the size of data we can expect to see in e.g. 3, 6, 12 months time.
We should also be aware know that an example set of data may not cover all possibilities for developers new to IATI
Our code should be secure¶
When relying on external code (e.g. wordpress) - we should be on an alert list, we should update as soon as possible where necessary.
We should assess our own code for vulnerability
We should know that our deployed code is working properly¶
This could mean monitoring that the application is ‘up’ - pingdom for example
We should know that cron jobs have run
Our code should be simple to deploy and update¶
When creating an application, consideration of the ease of deployment, including upgrades should be considered.
Are we using any other tools to help us monitor our code?¶
For example, linking into webhooks or services such as Travis
Is this code language aware?¶
Can it handle unicode correctly? Does it need to handle translations and display text in differnet scripts?