development-workflow.md

KBase Development Workflow

Contents

• Prerequisites
• Summary
• Process Details
  • 1 .Set Up A Feature Branch
    • Option 1: Repo Branch
    • Option 2: Personal Fork
    • Create Branch Demo
  • 2. Develop Improvements
  • 3. Create Pull Request
    • Option 1: From a Branch
    • Option 2: From a Personal Fork
    • Create PR Demo
  • 4. Test Image
    • Build Develop Image Demo
  • 5. Merge Pull Request
    • Merge Pull Request Demo
    • Automatic Image Tagging

---

Prerequisites

The KBase Development workflow requires the following:

1. Three branches must exist, named:
   • main or master
   • develop
   • inbox
2. The pr_build.yml and prod_release.yml workflows described in the New Repository and Existing Repository sections must be present in the repo.
3. The branch rules discussed in Enable Branch Rules must be enabled.

Summary

• All work is performed in feature branches or personal forks
  • Branches should matching any JIRA or GitHub issue numbers
• Feature branches are merged via pull requests to the develop branch
  • A test image named {REPONAME}-develop is automatically created with a tag that matches the pull request number (e.g.{REPONAME}-develop:pr-42)
• Once a pull request is merged to develop, the image created above is automatically tagged as latest
• Images must initially be made public by an administrator
• Once the code in the develop branch is ready for release, the Release Workflow is used to create the production image

---

Process Details

Before proceeding, please confirm that all prerequisites above are met.

1. Set Up A Feature Branch

To start development, first create a feature branch off of develop, either in the KBase repo, or in a personal fork.

Option 1: Repo Branch

Expand For Instructions

If you have write access to a repo in the github.com/kbase organization, you can create a feature branch directly in the repo. Simply:

1. Ensure you're currently viewing the develop branch.
2. Create a feature branch from develop (not main!), giving it the same name as the relevant Jira or GitHub issue (e.g. PTV-510).

Option 2: Personal Fork

Expand For Instructions

If you don't have write access to a repo in the github.com/kbase organization, or if you prefer working in a personal fork, do the following:

1. Create or update a personal fork of the KBase repo in question.
2. Ensure the develop branch is up to date with the original KBase repo.
3. Create a feature branch from develop (not main!), giving it the same name as the relevant Jira or GitHub issue (e.g. PTV-510).

Create Branch Demo

Expand For Demo

2. Develop Improvements

Perform any development work in the feature branch created above. Commit early and commit often!

3. Create Pull Request

When any changes in the feature branch are ready for testing and merging to the develop branch, create a pull request using one of the following techniques:

Option 1: From a Branch

Expand For Instructions

If you're using a feature branch in the original github.com/kbase repo, simply:

1. Create a pull request from your feature branch, to the develop branch.
2. Review the newly created pull request, and update your feature branch if requested.

Option 2: From a Personal Fork

Expand For Instructions

If you're using a personal fork:

1. Create a pull request from the feature branch in your fork to the inbox branch in the original github.com/kbase repo.
2. Review the newly created pull request, and update your feature branch if requested.
3. Request that a developer with write access to the original repo review the pull request to inbox.
4. Once merged to inbox, request that a developer with write access to the original repo create a pull request from inbox to develop.

ℹ️ Why We Use inbox With Forks
Due to a security feature in GitHub Actions, pull requests from a fork can't make use of automated build scripts in the original repository. Pull requests from forks must be merged to inbox first, to ensure no malicious code has been added to the workflow code. Once merged to inbox, the build scripts will work normally via a pull request from inbox to develop.

Create PR Demo

Expand For Demo

4. Test Image

When a pull request to develop is created or updated, the pr_build.yml workflow will automatically start building a test image. To utilize this image for testing in non-prod environments:

Expand For Instructions

1. Allow the pull_request job in the Bueild & Tage Image on PR workflow to complete.
   • The status of of the build will be visible in the Checks section of the pull request
   • The status can also be viewed from the Actions tab.
2. Once the build completes successfully, click the Code tab in the repo.
3. Navigate to the Packages section on the right of the screen, and click {REPONAME}-develop.
4. In the packages view, confirm that an image matching the pull request number exists (e.g. {REPONAME}-develop:pr-42).
5. Test this image, and optionally deploy to a non-production environment.

⚠️ Where's The Image?
If the {REPONAME}-develop image doesn't appear under the Code tab under Packages, ask a KBase administrator to make the image public & link the package to the repo.

Build Develop Image Demo

Expand For Demo

Demonstrates:

• The automatic build process
• How to view builds in the pull request
• How to view builds in the Actions tab
• Location of the {REPONAME}-develop images
• How image tags match their respective pull request numbers

5. Merge Pull Request

Once all builds pass, and the images have been tested in a non-production enviroment, request a pull request review from another developer with access to the repo in question.

After approving and merging the pull request, please delete the source branch (unless the source branch is inbox, due to the forking workflow)

Merge Pull Request Demo

Expand For Demo

Automatic Image Tagging

After the pull request is merged, the Build & Tag Image on PR workflow will trigger the tag_on_merge job, which automatically tags the image created above as latest. This image is now ready to be deployed to CI or other non-production environments.

🎬 Coming Soon - Continuous Delivery
Once all non-production environments are migrated to Rancher 2, developers will have the option to automatically deploy the latest image to a development cluster when a pull request is merged!

---

|| Previous: Enable Branch Rules || Home || Next: Release Workflow ||