Tech team docs

# Changes

# Intro

This section presents our standard framework for developing changes. By changing we refer to either new features, large changes to existing features or substantial changes in our security processes - in short it is everything that is not patches (see separate section)

# Change process overview

From a engineering point of view, the process we follow is outlined here:

  1. Design the user experience – high level / low fidelity
  2. (optional depending on feature) Design the more detailed UI using Figma (high fidelity)
  3. Create a DRAFT PR on Github (see creating PRs)
  4. Involve others to reduce risk
  5. Ensure new and existing tests all pass
  6. Test on development server
  7. Refactor and document key assumptions
  8. Clean up code
  9. Update PR status to being reviewable
  10. Team review of PR
  11. Review of release checklist

Steps marked in bold is specified further below

# Before you start coding

Before you even start coding there are quite a few considerations you need to consider:

  1. Do you understand what we are trying to do from a user perspective?
  2. Do you understand which stakeholders we are serving (clients, internal, specialists, PPT users)?
  3. Do you understand what success looks like?
  4. Which repositories will you be working in?

It is essential you get a good understanding of the above. Please make sure to discuss these aspects before even opening your IDE.

# Determine scope - aim for multiple pushes

If the scope of the given Jira card / user story is not fully detailed, it is essential to clearly scope the work and write it down (should be stated in the PR description and Jira link).

In general you want to split the scope into the smallest deployable PRs rather than merging all possible functionality into the same PR.

# Create a DRAFT PR on Github

We use draft PRs to ensure transparency and give others a chance to comment on work early on - and thus help to speed us velocity and increase code quality (it reduces rework later on)

The following is required as part of any new draft PR:

  • A Jira link for reference
  • Any comments that are essential for the person reviewing the PR

In general you want to make the life of the people reviewing the branches simple - to do this aim for the following:

  • Only make changes related to the described code
  • Don't implement linter changes until after the code has been approved

# Branch names

In general we have 4 types of branch names:

  • fix - written as "fix/XXX" used for bugfixes
  • refactor - written as "refactor/XXXX" used for refactoring
  • feat - written as "feat/XXX" for new features
  • ci - written as "ci/XXX" for changes related to continues integration changes e.g. cypress, GitHub actions etc.

The XXX should be a short 1-3 words that describe what the changes relates to

In a few cases we accept that multi bug fixes are bundled into the same PR / branch - but only when these are minor, non-urgent fixes

# Commit names

In general we are not very strict when it comes to commit naming - if everything else is done as described here you can relax a bit on this one. However, if you do want to follow our internal best practice please use the following approach:

  • Commit often
  • Commit when things "work"
  • If committing when things dont work include the term "wip" as part of the commit name
  • Use short names that describe what you have done
  • Dont use the same commit names over and over again - it makes it hard to track when things were changed

# Involve others to reduce risk

When writing code you are often ask to make a large number of small decisions. Some decisions are low-risk (easy to revert) and other decisions are "high risk" (takes a lot of time to revert).

When taking high risk decisions e.g. database schema, repository structure etc. it is always a good idea to involve a colleague.

In general, the higher the risk (e.g. measured as the number of lines changes in case of reversion) the more people (and more senior people) you want to involve.

# Update PR status to being reviewable

Before any PR is considered reviewable the following should have been done:

  • The code should be possible to merge into "main" (conflicts should have been solved)
  • Tests should have been written for all new back-end changes
  • Code must be DRY and refactored
  • Code comments should be clean (most often removed)
  • A label should have been picked (reviewable)
  • Added a full URL link to the staging / development server in which the work can be tested (see below)
  • When working on front-end heavy effort: A Loom video in which the work is presented

To make it easier for the team to test the work, you should add a URL to relevant front-end implications - including the specific test server

As an example - the PR should contain something like this:

URL: https://app2.teamnomore.com/#/manage/task/231231

To make this possible you want to configure the given server to host the branch using Forge

See a list of the test servers in Test section of this site

An example of good final "reviewable" PR:

Jira reference: https://slidehub.atlassian.net/browse/BV-237

Notes to reviewer: Uncertain about backend tests cover relevant edge cases

Example of a bad PR description:

Improving admin options - see Jira

# A few thoughts on git

Some important principles we should follow:

  1. The main branch must always be deployable – so that we can potentially conduct hot fixes if needed

  2. New features are worked on and tested in a separate branch – and is not merged with main until it is fully tested (and pass all existing automated test and tested in the front-end)

  3. Minor bug fixes and minor adjustments can be bundled in a branch in order to avoid overhead - but only for non-urgent fixes

  4. Anders can merge directly to main, but everyone else must conduct pull requests for review when submitting new code (the benefit of also being the CEO - it is my ass on the line)

  5. Once a repository is merged with the main branch it must be deleted. New work always requires a new branch.

# Deployment process

We use Envoyer (envoyer.io) to manage our deployments in production. And use Github Actions for our continuously integration testing.

We never push to production without ensuring that all tests pass on Github Actions first.

For any changes/feature associated with the front-end we make sure to carefully test the experience on our test servers first.

After a production deployment, make sure to reset the "task runners / daemons" (this is supposed to be done automatically, but fails in about 10% of the cases) – this can be done via Forge.

We use Forge for server configuration and for deploying changes to the staging servers.

# Team review of PR

For non-urgent PRs, all team members (not on vacation) should aim to review the PR and provide comments as they see fit.

The target is to review all PRs within 24 hours - unless it is weekend/holidays. To do this, we recommend that everyone start the day by review PRs from other

For urgent PRs (e.g. bug fixes, bottleneck etc) only 1-2 people are needed to ensure speed. Also, for urgent PRs make sure to explicitly ask people to prioritize the effort

# Review of release checklist

The Release Checklist - see checklists - must have been considered before a change is committed to the main branch

← Workflow →