Skip to main content Link Menu Expand (external link) Document Search Copy Copied
Wisk Evolution

The objective of this document is to specify the way we work with branches and a few simple rules

Branches

In every repository Wisk has 3 standard branches: develop/stage and master. These correspond to 3 Infrastructure Environments: wisk.dev, wisk.cool and wisk.ai

Once a code is pushed in any of these branches, using a GitHub action a new build is triggered. If the build is successful, it will be pushed live in wisk.dev/wisk.cool or wisk.ai.

Every ticket (besides small changes) should have its own branch. A git branch should start with a category. Pick one of these: feature, fix, refactor. The branch name should “snake-cased” and describe what changes the branch contains.

Workflow for the develop/stage/master branches

  • the development team pushes on the develop branch when a code is deemed to be stable
  • in case of code that might be unstable and break develop, a branch must be created
  • once the code is ready to be tested by the QA team, develop is to be merged into stage
  • once the QA team has validated the code, stage is to be merged into master

Notes:

  • once a code reaches develop, it is considered to be stable
  • once a code reaches stage, it is considered to be production ready and can be pushed to master at any point
  • this process assumes that the code is tested locally before being pushed to develop
  • once a code reaches stage it should reach production as soon as possible, otherwise we might reach complex cherry-pick situation that are hard to manage

Exceptions:

  • for Web we have two special branches: feature1 and feature2 available at https://feature1.wisk.dev and https://feature2.wisk.dev. These are used when we have an experimental code that if pushed to develop might introduce instability.
  • for API it’s possible to deploy a given branch in the develop server (in order to test it on wisk.dev). To do this, you can go to github actions page for API (https://github.com/WiskSolutions/wisk-api/actions) and select the manual-build-docker; then select the needed branch an click on Run workflow. Once built and deployed, the new code will be available on wisk.dev environment.
  • The QA Team might be asked to test on develop on special occasions: for example when we have a new feature that is not yet ready to be tested by the QA team.

PRs and when to make one

  • PRs have two purposes as WISK:
    • collaborate with the teammates and get their opinion
    • share your knowledge, so that a teammate will be able to work in the future on the code without onboarding
  • every branch should have a PR
  • the PR should be opened and closed in max 2 days, otherwise we’ll get to many stalled PRs
    • this requires that we move fast to avoid rebasing and conflicts
    • also forces the PRs to be for the smallest code feature possible
    • if working on a big task, it may be required that the task is split in multiple smaller PRs
    • it allows us to have incremental delivery to the clients
    • this is proven to minimize bugs and more digestible PRs
  • separate the PRs per feature unless there are a few very small fixes

PR Management

This should be the process that PRs go through before merging:

  • Author should request for reviews from the team. GitHub ususally automatically does this.
  • 50% of the team should review and approve the PR.
    • For example if a team contains 5 members, and 1 member made the PR, 2 other members should review and approve the PR before merging.
    • The author should self-review their PR and leave comments about the parts of the code that they think might be hard to understand.
    • Reviewers should praise the good parts of their teammate’s code, while being critical about suboptimal parts of the code.
    • Reviewers should leave comments if they have questions about parts of the code.
    • The final merge should be done only by the original author.
    • If there are conflicts, the branch should be rebased on develop manually and all conflicts should be resolved before merging.
    • The author can enable “Auto Merge” on GitHub to indicate their PR is final and they don’t plan for any final touches.
  • Memebers can set their status to “on vacation” and GitHub won’t automatically ask them for a review:
  • Generally, every time you touch a function try to leave the function in a better state than it was before and don’t hesitate to clean it up.
  • After merging the PR, the Monday task should be marked as ‘Product Review’ or ‘Done’ based on QA requirements.
  • If everything went fine, the develop branch should be merged into the stage branch.

All these are general rules. You can override them if needs be. For example someone could merge another member’s PR if there is a time-sensitive need while leaving a comment in the PR mentioning why they did that.

PR Merging and Monday task management flow 

sequenceDiagram
    participant Dev as Developer
    participant R as Reviewer(s)
    participant DevelopBranch as DevelopBranch
    participant MT as MondayTask
    participant Stage as StageBranch
    Dev->>R: Assign PR for review
    R->>Dev: Review PR
    Dev->>DevelopBranch: Merge PR into develop
    Dev->>MT: Mark task as Product Review or Done
    Dev->>Stage: Attempt to merge code into stage

How to merge from develop into stage while stashing any locally (not pushed) changes

  • Stash local changes
  • Merge develop into stage
  • Checkout stage
  • Push stage to remote
  • Checkout develop
  • Pop stash
  • please see this loom: https://www.loom.com/share/e695817137ec46c6986c7173be09aaed

Monday worflow

Sections:

  • Backlog
    • In Progress
  • Current workload (Dev environment)
  • In Review before Release (Stage environment)

Commit

Every commit message should in short describe the changes made in the code and it must contain a monday task link in a new row below the commit message. This will link the Monday task to the commit.

img_11.png

The link will look like this: https://wisk.monday.com/boards/50205658/pulses/3872562874