7  Software Development

Our project will primarily use GitHub for project and code management. Here are the key features we’ll utilize:

This structure ensures that while issues handle the immediate and detailed aspects of development, PRs and releases provide high-level summaries and documentation that are essential for understanding the progress and outcomes of our work.

7.1 Issues

We have several types of issues each with some suggested structure and naming conventions

  • [Release]
  • [System Enhancement]
    • Purpose: issues describe new features or enhancements to the system. These can be used to epics within a release.
    • Example: [System Enhancement] ETL Orchestration
    • Naming: [System Enhancement] {epic label}
    • Labels: System Enhancement
  • [Pipeline]
  • [SOP]
    • Purpose: issues describe new SOP to add to project documentation
    • Example: [SOP] Storage
    • Naming: [SOP] {SOP label}
    • Labels: SOP
  • [Notebook]
    • Purpose: These are floating notebooks for EDA or tech-research meant to give flexibility to store ideas/code but have them accessible. No guidelines for attaching to issues, PR or releases. but you could if you want. These are unstructured and meant tallow people to get ideas/code down on paper.
    • Example: [Notebook] Feasibility tests and benchmarks - PRISM pipeline with Terra
    • Naming: [Notebook] {Notebook name}
    • Labels: Notebook

7.2 Branches

Now that we have cleared defined our scope of work, we most of the time will want to create a GitHub branch to work on a specific issue. Branch naming does not matter too much so we recomend that the easiest thing is to just utilize the GitHub Issues page to Create a branch as shown in the snip below

You can Check out on remote thne pull to bring the branch into your own local environment for work.

7.3 Branch Protection

By enabling each analyst to work on their isolated environment via a branches we can allow collaboration on the same codebase to occur asynchronously. However, there is always a special branch or copy of the code called main. This branch represents the single source of truth for our project and because of that we want to set some rules to ensure any changes to the main branch is reviewed and no accidental changes are made. GitHub allows us to set these rules through a mechanism called GitHub branch protection rules. Here we document branch protection rules for CCUH.

We first navigate to the repository Settings > Branches page

We have two options to add a custom branch ruleset via the Add branch ruleset button or use some generic branch protection rules. We will opt for the latter as we only want to implement some standard rules to protect the main branch.

We click on the Add classic branch protection rule button and start specifying protection rules for the main branch including:

  • Require a pull request before merging: When enabled, all commits must be made to a non-protected branch and submitted via a pull request before they can be merged into a branch that matches this rule.

    • Require approvals (1): When enabled, pull requests targeting a matching branch require a number of approvals and no changes requested before they can be merged.

    • Dismiss stale pull request approvals when new commits are pushed New reviewable commits pushed to a matching branch will dismiss pull request review approvals.

  • Require status checks to pass before merging: Choose which status checks must pass before branches can be merged into a branch that matches this rule. When enabled, commits must first be pushed to another branch, then merged or pushed directly to a branch that matches this rule after status checks have passed.

    • Require branches to be up to date before merging: This ensures pull requests targeting a matching branch have been tested with the latest code. This setting will not take effect unless at least one status check is enabled (see below).

  • Require conversation resolution before merging: When enabled, all conversations on code must be resolved before a pull request can be merged into a branch that matches this rule. Learn more about requiring conversation completion before merging.

  • Do not allow bypassing the above settings The above settings will apply to administrators and custom roles with the “bypass branch protections” permission.


These were all the rules selected for CCUH; overally, its a rather protective workflow that requires everyone - even admin roles - to utilize Pull Requests to modify main. While this may be more work, we believe these will promote intentional work and enforce documentation of changes.

A snip of the Branch protection rule as we selected above looks can be found below.

7.4 Pull Requests

CCUH we conceptualize signitifcant growth steps for our infrastructure in two main abstractions New Pipelines and New SOP . Likely the types of epic abstraction will increase but for now we will provide recommendations about how to utilize PR to document these contributions.

  • [Pipeline]
    • Purpose:
      • to provide high level summary of pipeline contributions
      • link to issues issues involved in building this pipeline to allow for drill down into details.
    • Example: New Epic Pipeline: ccuh_prism_zonal_stats_v1 (PA PRISM Zonal Stats)
    • Naming: New Epic pipeline: `{pipeline_instance}` {pipeline_label}
    • Labels: Pipeline
    • Content:
      • Overview
      • Metadata
      • Issues
  • [SOP]
    • Purpose:
      • docuement addition of documentation
      • PRD: summarize why, proposal, plan for SOP
    • Example: New SOP - storage
    • Naming: New SOP - {SOP label}
    • Labels: SOP

7.5 Release

So when it comes to release time we can just go to GitHub and Generate release notes button and automate some of the reporting of our key abstractions.

For example a drafted release note might look like this: