Source control and the developer's workflow

The LiteFarm GitHub repository uses various branches for specific purposes.

• integration is the default branch, used to integrate the work of multiple developers. Proposed changes to this branch (pull requests) must pass pre-integration peer review before they are merged in. When approved changes are merged, the branch is automatically built and deployed to the pre-production environment generally known as “beta”. When the changes have been verified and validated, the commits move to …

• main, a release-ready mainline branch. On this branch, tags are used to identify release candidates for scheduled production releases. When changes are actually released to production, the tag is associated with a GitHub release. So the contents of this branch, up to the latest GitHub release tag, represent code in production; subsequent commits represent code waiting for the next scheduled production release.

• LF-{n}/{description-in-kebab-case} describes an informal naming convention for topic branches. (“Topic branch” is the original term that generalizes the more popular concept of “feature branch”.) Most LiteFarm development tasks are defined by a Jira ticket. Each ticket has a unique identifier that consists of a project prefix (usually LF- for LiteFarm) and a sequential number denoted {n} above. Topic branches are typically named for the corresponding Jira ticket ID, followed by a slash, followed by a more readable description in kebab-case. Example: LF-2258/fix-map-page-history-state.

Working a ticket

This section assumes that you are familiar with git and GitHub concepts like clones, branches, commits, pull requests (PRs), and merges. If you are not, or feel uncertain, ask for guidance. The best learning resources will depend on the specifics of your knowledge, experience, and comfort level.

The following diagram provides a visual overview of LiteFarm workflows. Horizontal “swimlanes” group the activities by organizational role.

The bottom lane depicts your work as a software developer. The endless process “starts” when you begin working a ticket. When you submit a PR for that ticket, your focus shifts to reviewing a waiting PR that a teammate submitted for some other ticket.

The following bullets follow the Developers swimlane, with a focus on your source control activities. The Github Jira integration should automatically update Jira ticket status as indicated in the flow diagram.

• In your clone (not fork) of the LiteFarm repository, create a topic branch from integration, following the naming convention for topic branches. Jira autogenerates the git command for creating a topic branch for a particular ticket for you, you can copy this command by clicking on “Create branch” in the details section of the Jira ticket.

  Open

  

• Commit to your branch frequently. Do not wait until the changes are (nearly) complete. Commit messages for Work In Progress often start with WIP and should provide a running log of your progress on the ticket (examples below). At a minimum, push your commits to GitHub at the end of each day that you make changes.

Open

• When you are satisfied that your work is ready for pre-integration peer review, create a PR from your branch to integration.

• Your PR will trigger a set of automatic checks and tests. GitHub will show their status on the PR.

  If these checks find problems, address them by pushing more commits on your branch. They will append to your existing PR.

• When the checks have passed, pre-integration peer review begins. The PR that you have just created is waiting for review by a teammate.

  1. The first reviewer is whichever teammate next submits a pull request of their own. This reviewer should assign themself as Reviewer on your PR so that everyone can see the review is in process.

  2. If the first reviewer does not agree that the PR meets expectations, they identify changes that need to be made and reject the PR with a request for those changes. You can submit these changes by pushing additional commits to your branch; they will be added to the existing PR where the first reviewer can evaluate them. This cycle can repeat until the first reviewer approves the PR.

  3. When the first reviewer agrees the PR meets expectations, they approve it and assign a second reviewer from a designated set of experienced LiteFarm developers. This may lead to more cycles of requested changes and new commits. In particular, the second reviewer will request any changes needed to resolve conflicts that prevent a clean merge with the integration branch.

  4. When the second reviewer approves the PR, they will merge it into theintegration branch, at this point the Github Jira integration should automatically update the ticket status from Development to Verification . The updated integration branch will build and deploy to the pre-production environment where verification and validation are performed. The second reviewer can be selected using the round robin automation on Github currently name LiteFarmOrg/reviewers

• Notice that when you create a PR (previous bullet), you assume the role of first reviewer for the oldest waiting PR from someone else, and begin the process described under the previous bullet.