How To Build a Feature

A brief best-practice guide for how we build features at the Legal Innovation Lab Wales

Note: This is a living guide. We follow these steps on a day-to-day basis. We will tweak and update this guide as we go along and learn form our mistakes

Start on Jira

After a feature is outlined or described by stakeholders it will be added to the Backlog column on Jira. When creating the ticket, as much detail as possible should be given. We won’t always be able to provide a full user story, but give as much information as you can as early as you can. The backlog column is roughly prioritised with the more urgent tasks appearing towards the top.

When you come towards the end of the task you are working on, select a ticket from the top of the Backlog, assign it to yourself and move it to Next Up.

With the ticket in Next Up,there is the opportunity to refine and expand the feature description. The aim is to fully describe the feature as well as we can and how it is going to look when finished. You can ask for input from one or all of the rest of the team.

When you are happy with the detail on the ticket, move the ticket to In Progress.

Developing the Feature

Git Guides: How and Why, Handbook

Ensure your local branches are up to date then create a new branch for your work. The branch name should be prefixed with the type of ticket and then start with the ticket ID and the ticket title.

Branch prefixes include: feature/, bugfix/, hotfix/, refactor/ , other/.

Examples: feature/dt-124-how-to-build-features, bugfix/sp-206-fix-broken-thing, hotfix/fix-for-this-issue

When working on a ticket, commit regularly. Each commit should contain one discrete change / improvement and should be made when the codebase is in a state which you want to remember. Each commit which directly relates to the task should have the ticket ID at the start of it.

As you are working on the feature, build it to the best of your ability, leveraging your experience, creativity and ingenuity. If something comes up which you are uncertain about, or if you think of something which could be a good addition to the feature, go back to the ticket on Jira and ask about it there.

There are a couple of principles which we try and follow when building features. Most of which are common software development principles: KISS, SRP, and DRY. One that is less common is what I call "Build Something Beautiful". This realates to the principle Rails' docterine of optimising for developer happiness.

Build Something Beautiful is about writing beautiful code, but more importantly about thinking about the interface first. No one really likes testing functionality on something which has no styling, so its worth investing the time to consider the interface first and style the project earlier rather than later. Make it beautiful! The interface is the product, its what the end user is going to see. It's going to constantly be revised through the process but having something there from the start makes everything else easier and more enjoyable

When you’ve finished work on the ticket, push your code to GitHub and create a pull request (PR). Your PR title should contain the ticket ID and a short title, probably similar to the ticket title. The description of your PR should be an explanation of what you have done and how, including screenshots if there is a front end / UI component. Then request a review from the rest of the team. PRs are designed for the team to check your code makes sense, does everything its supposed to and meets our standards.

From the “How and Why” Guide:

Once a Pull Request has been opened, the person or team reviewing your changes may have questions or comments. Perhaps the coding style doesn't match project guidelines, the change is missing unit tests, or maybe everything looks great and props are in order. Pull Requests are designed to encourage and capture this type of conversation.

You can also continue to push to your branch in light of discussion and feedback about your commits. If someone comments that you forgot to do something or if there is a bug in the code, you can fix it in your branch and push up the change. GitHub will show your new commits and any additional feedback you may receive in the unified Pull Request view.”

We strongly recommend reading the guides, if you have questions following that don't hesitate to get in touch.

Back on Jira

When you code is up for PR, move the ticket to Pending Review. Now you should pick another ticket from the Backlog and move it to Next Up. You can also spend some time reviewing any other open PRs.

GitHub - Reviewing Code

When reviewing PRs we should do several things:

1. Go through all the code changes, leave comments
   1. anywhere there is something you don’t understand
   2. anywhere that you think something could be improved
2. Pull the branch and run it locally, double check everything works as intended.
3. Think about what has been built, if it works as intended, meets the requirements and if there are any ways it could be improved. If you have any suggestions try and explain the How and Why in as much detail as possible.

You can always get involved and collaborate. If there is a small bugfix, you can make the change and push the code onto the branch. If there are design or feature changes you think could work better, create another branch and an additional PR back to the feature branch.

There’s no rule that says the person who raises the PR has to be the sole contributor to it. If there is agreement about a feature change, it might make more sense for the person who has the vision for the changes to write the code, not the person who started on the branch.