Skip to main content

Handbook 📗

Here we outline 5app's developer best practices - at the risk of appearing dogmatic.

It is [like us] a work in progress and open to suggestion and adaptation.

Fundamentals​

It's important that we openly discuss and share the work we have done, so that we learn off one another, share problems and solutions. Possibly all of the best practices revolve around good communication.

When stuck while working on an issue, feel free to explore and research solutions. However, also know when to reach out to your colleagues for help.

Code less​

Coding should not take up all of your time, as there's lots to do besides.

Inspect and improve tickets: Have a look at the tickets which are new or are being worked on, if it's a bug try to replicate it and let everybody know the results. Add your comments, emoji or even just beautify the markdown.

Review Pull Requests: Perhaps before you take on another ticket, checkout open Pull Requests and see if you understand what's going on, if not ask. If you do, and you're happy, give it your stamp of approval.

Read More: Try out new things and make suggestions to the team.

Naming Conventions​

In the code​

We aim to use Camel Case in the FE e.g. isDeleted and Snake Case for anything API related. e.g. is_deleted

When naming components, use Pascal Case, e.g. const Checkbox = () => {...}

General good practice​

  • Consistency - Pick One Word per Concept — Use the same concept across the codebase

    fetchData() vs getData() vs retrieveData()

  • Meaningful - Characters are cheap, confusion is expensive

    ❌✅
    const users;const userCount;
    const friends;const friendsOfCurrentUser;

  • Avoid Encodings - Avoid unnecessary encodings of data-types along with the variable name

    ❌✅
    urlStringurl
    numberOfMembersIntmembersCount
    namesArraynames;

  • Use Pronounceable Names - Avoid tongue twister or a non-searchable words

    ❌✅
    first name labelconst lblFName;const firstNameLabel
    now date timestamp since 1970 in millisecondsconst nowTsMsconst nowTimeStampInMS

Branching Model: Git Flow​

Follow the Git-Flow branching model

  • Master is always production deployable
  • Staging is the next release, and made available for regression tests
  • Dev is the culmination of a sprint
  • Feature branches are based off dev

This flow might not make sense for all projects which don't have a manual QA function.

Feature Branches / PRs​

  1. Use semver in the title e.g. feat(sharing): allow for users
    • this helps us generate the changelog
  2. Include the fixes #1337 in the body so that tickets can be automatically closed.
  3. PRs should be atomic. Any refactoring tasks should be added to a new PR especially for refactoring.
  4. KISS (keep it simple stupid).
  5. Add a concise and clear description to the PR along with any concerns you might have over your changes.
  6. Request PR reviews from people on the team.
  7. Once approved please Squash Merge this will again make it easier to read the changelogs.

Working on Epics​

  1. Epics can be big, so they should be broken down into smaller tasks, ideally in a way that enables many people on the team to work on the epic at the same time.

    If you have a feeling that your task is too large in scope for a single ticket, reach out to the team to discuss how best to split it up further.

  2. When an epic is to be tested, it maybe required to create a temporary branch to test all the features of the epic in one place. This will allow the stakeholder to provide feedback, as well as QA testers the ability to test the feature in a relatively stable environment.

Commit Messages​

Commit messages provide a valuable summary of the code changes made. A good commit message will look like:

fix(homepage): change api request, #1337

  • semantic commit message: starts with fix, feat, test, style, docs, refactor
  • issue number: appears at the end of the message and provides a way to track the change
  • message: is short and concise

Merge rules​

When merging from dev, staging or master always merge (Never Squash Merge), as the history is important coming from those branches.

When merging from a feature branch the history is less important and the branch can be squash merged.

Definitions of Done and Ready​

See also Miro board results of DOD discussion from the 13.01.2023.

DOD for a Feature​

For starting dev work​

  • Feature is clearly defined
  • Feature is broken down into issues

For completing dev work​

  • All issues completed or deferred

  • Implementation matches designs & reasonable amount of polish has gone into it

  • Accessibility checked with screenreader (Focus on keyboard navigation) - Devs and maybe QA

  • Documentation of what the feature does in Docs if needed (for Devs)

  • Update pitch doc if needed (for Marketing uses)

  • "Dev" feature flags removed

For completing the feature​

  • Validation of feature in prod (using stats/feedback)
  • Feedback has been taken into account and necessary improvements, changes made
  • Feature flag removed

DOR for an Issue​

Bugs​

  • Issue can be reproduced (ideally) or has a detailed description
  • Bug label applied to issue

Small changes​

  • Description of change in ticket with required info e.g. copy
  • Appropriate label(s) applied to issue

Big changes​

  • Issue has been discussed in dev team where needed
  • Description of feature in docs
  • Designs ready for at least most edge cases
  • Appropriate label(s) applied to issue
  • Clients informed if applicable

DOD for a PR​

For requesting reviews​

  • Ticket requirements met

  • UI/UX complete

    • i18n for new copy
    • Accessibility checked with screenreader (Focus on keyboard navigation)
    • UI changes checked on mobile device

  • Testing

    • Tests written and working (e2e, integration tests)
    • Instructions have been manually tested, changes work on child hub

  • Documentation added / updated:

    • New base-level components documented in Storybook
    • Api Documentation
    • ReadMe or Docusaurus docs

  • PR contains all required information

    • PR has comprehensible description
    • PR has screenshots / screenrecordings of UI changes / flows
    • Test notes for QA team

For merging​

  • Reviewed & Approved by another Dev
  • Tests passing in pipelines
  • Labels & Milestone added to ticket

For closing the issue solved in the PR as "done"​

  • Passed QA testing on dev and staging