Table of Contents

• KISS
• Version control
• Workflows
• Repository structure
• Branches vs personal forks
• Unit of work
• [WIP] Deployment pipelines
• Django
• Footnotes

KISS

As in "Keep It Simple Stupid", yes. We attempt to apply this principle to all aspects of web-development, from day to day workflows to back-end and front-end code, dependency management and deployment pipelines.

That said, this strife for simplicity is a never ending battle, so expect inconsistencies, because there's always something that no one got around to making better.

This also means that Institute's web projects don't rush into adopting the trendiest tech and share as much boilerplate as possible, because trends come and go, while Institute's projects tend to survive for years on end.

Version control

Workflows

Repository structure

All web project's repositories have the same structure:

• main is the "next release" branch: it contains code ready to be deployed to production;
• production is what is currently live in production.
  • "release" means git fetch origin main:production && git push origin production;
  • nothing gets merged or pushed directly into production, only via main;
• no force pushes to main or production.

Any changes made in repository are based off of latest main and are merged back into main.

Branches vs personal forks

Web projects are normally maintained by a small team, in which everyone has commit access and are responsible for the outcomes of those commits, so creating branches in the project's repository is an acceptable day to day workflow.

This also has a number of benefits over working in personal forks:

• it's easy for multiple people to collaborate;
• everyone can see what is being worked on at the moment and by whom;
• no need to think about pushing and pulling to and from a correctly configured remote.

The gist of this workflow:

1. checkout the repository you need to work on;
2. pull its latest main;
3. create a new branch (e.g. git checkout -b my-shiny-new-feature);
4. work in that branch;
5. push that branch to remote if you want to share it with someone, or simply to make sure it's saved (e.g. git push -u origin $(git branch-name));
6. when ready, create a pull request from that branch;
7. when pull request is ready, squash and merge that branch into main;
8. delete my-shiny-new-feature from the repository.

Unit of work

Ideally, each commit in main must do one single self-contained thing, easy to review and easy to revert ¹.

A good indicator of a self-contained change is whether or not it's possible to summarise it in a 70-75 characters or less. In the commit message, this summary phrase can be followed by an empty line and a short paragraph containing extra details.

Here's an example of a good commit message.

If you are struggling to summarise your change, it's possible that it contains too many things at once. In this case it might worth splitting the work into separate pull requests, e.g. a "Bug fix of Y", "Refactor of Y necessary to do X" and "Adding X to Y" should be separate commits, not one.

This way git log --oneline gives a readable overview of what has been going on in the project.

All of the above applies to the commit that ends up in main: in the branches that live only while you work on a particular feature you are free to do whatever you like.

[WIP] Deployment pipelines

• Ansible;
• SSH access to production machines;

Django

All projects (with exception of OpenData at the moment of writing) use a single settings.py module which expects all configuration parameters set via environment variables stored in .env file in project's direcory.

For convenience of local development, some projects use python-dotenv to load contents of .env file to avoid having to source it before running ./manage.py. However python-dotenv should never be installed in production, because it is not equivalent to Bash source or systemd EnvironmentFile= directive, and doesn't handle escaping in the save way (e.g. it will trip over 'aaa'"bb'bb"'ccc' which is a perfectly valid escaping of aaabb'bbccc).

Footnotes

1 Commits with database migrations often cannot be simply reverted, manual actions are usually required to avoid broken production. ↩