Skip to content

The cFS CCB Process

dzbaker edited this page Jul 6, 2022 · 10 revisions

The cFS Configuration Control Board (CCB) reviews proposed design changes on a weekly cadence. This is done by evaluating open issues and pull request that are marked with "CCB" prefixed labels.

Specifically, we ask that pull request (PR) and issue authors mark their submissions with the labels "CCB:Ready" or "CCB:FastTrack" when they are ready to discuss the item.

Reviewing Pull Requests

The bulk of the CCB discussions focus on code review of new pull requests(PR). A PR marked with "CCB:Ready" can be either finished or under development. We ask that PR authors who wish to mark things for review first request a review using GitHub's "reviewers" panel. If you don't know who to tag, visit the cFS Subject Matter Experts List to see who is better equipped to tag each repository. Though this step is not required, it usually accelerates how quickly a pull request will be merged into the codebase.

Fast Tracked Pull Requests

The label "CCB:FastTrack" is used by authors to request a pull request be merged quickly with minimal CCB review. For fast-tracked pull requests, please request a review using the GitHub interface and tag the maintainers in the cFS Subject Matter Experts List. Fast-tracked pull requests tend to be small documentation changes or urgent bug fixes needed by a stakeholder.

Reviewing Issues

An issue marked as "CCB:Ready" usually requires design-focused discussions with the cFS Architects and NASA stakeholders. Some examples include changes to the API, proposals for deprecation, and other proposals that change how cFS functions, is built, or deployed. Typically, issues affecting multiple components or stakeholders will be discussed at the weekly CCB meeting and then a topic-specific discussion will be scheduled later in that week.

What happens to issues and pull requests after CCB Review?

Once a pull request has been discussed at the CCB it can be either approved, marked for changes, or assigned for discussion.

Approved Pull requests

Pull request that are approved at a CCB are included in the next integration candidate cycle. The cFS bundle and each of its components has an integration-candidate branch that serves as a testing ground where things get merged before putting them on the main branch. The pull request flow happens on a weekly cadence as indicated in the diagram below.

cFS Pull Request Flow

Pull requests marked with changes or for discussion

Sometimes the CCB determines that a submitted pull request is not ready or warrants more discussion. In these cases the pull request can be

  • marked with specific changes for the author to implement,
  • closed and reopened with a new or different approach,
  • split up into multiple pull requests to accelerate implementation of approved components,
  • tagged for review by specific subject matter experts, often the architects, or
  • tagged with a "splinter" label indicating that an in-depth, synchronous discussion needs to happen

Preparing for the CCB as a cFS Maintainer

cFS maintainers use the cFS framework Kanban Board (internal-only) to place issues and pull requests from across the cFS framework's repositories into the appropriate status column.

Adding issues and pull requests to the upcoming CCB's agenda.

We use the "CCB:Ready" label as a queue for the next set of issues and pull requests to discuss.

Useful search keys

The following GitHub search keys are useful for finding new pull requests and issues for discussion at the CCB:
label:CCB:Ready label:CCB:FastTrack is:new is:pr is:open

Merging Pull Requests after a CCB

The following only applies to pull requests in the cFS-Framework: cFE, osal, PSP, ci_lab, to_lab, sch_lab, sample_app, sample_lib, cFS-GroundSystem, elf2cfetbl, and tblCRCTool.

Setting up your local git environment

  1. Set up git access using ssh keys.
  2. Fork each repository in the cFS-framework including the bundle.
  3. Set up two remotes on your local environment: origin (nasa org repos) and fork (you can name this one as your username)
  4. Enable automatic pull-request branch fetches: Add the following to your .git/config file in your bundle repo.
[remote "origin"]
		fetch = +refs/pull/*:refs/remotes/origin/pull/*

See https://gist.github.com/piscisaureus/3342247 for a more detailed setup

This will enable you to check out and merge pull request commits as local branches.

Prepare the integration candidate branches

The IC branches in each repository are meant for batch combination of approved PRs. These merges are done locally.

Before getting started with batch merges, make sure that both the remote and your local integration-candidate branches for all submodules are even with the main branch.

An easy way to do this is as follows:

cd cfs
git checkout main
git pull
git checkout integration-candidate
git rebase main
git log -1

THe output of git log should show that you're "even" with the remote and main. For example

cfs % git log -1                                 
commit 89d0bda572edc99b868a9f4ab8d214755d38602e (HEAD -> integration-candidate, origin/main, origin/HEAD, nasa/main, nasa/integration-candidate, astrogeco/integration-candidate, main)
Merge: e158073 84e75f6
Author: Gerardo E. Cruz-Ortiz <59618057+astrogeco@users.noreply.github.com>
Date:   Wed Jun 22 11:42:32 2022 -0400

    Merge pull request #505 from nasa/integration-candidate
    
    cFS Bundle Integration candidate: Caelum-rc4+dev11

The first line above shows that the local HEAD commit 89d0bda572edc99b868a9f4ab8d214755d38602e in the integration branch is also the head commit for the origin main and integration branches as well as for other remotes. Note that in this example there are actually three remotes origin, nasa, and astrogeco.

Merge approved PRs in submodules

Navigate to a local submodule that has open and approved pull requests. Merge PRs one by one by using the following commands:

cd COMPONENT-SUBMODULE
git checkout integration-candidate
git merge origin/pull/XYZ/head --no-ff

where XYZ refers to the PR's number. The no-ff flag forces git to create a new commit message. The message should read as follows:

Merge pull request #XYZ from author/fork-branch-name

Fix #ABC, Pull Request Title

Then, push the local integration-candidate branch containing the newly-merged PR to the nasa remote's integration candidate. This will kick off the github actions workflows.

In parallel, update the submodule hash at the bundle level:

cd CFS_DIR
git commit MODIFIED-SUBMODULE

For the commit messsage, use

IC:CodenameBaseline+devNUMBER

nasa/COMPONENTNAME#XYZ, Pull Request Title

This links the merged PR in the submodule with the bundle repository. Note however, that we've removed the issue number #ABC reference. Then, push to the integration-candidate branch in the nasa cFS bundle repository.

Prepare the cFS-Bundle integration candidate pull request

Once there's at least one new commit at the bundle-level integration-candidate, open a new pull request in that repository. For the pull request information add the pull request titles for each submodules. If appropriate, cross-component pull requests that falls within a shared topic, can be grouped using small "sections" in the PR description.

Update version.h and Readme.md Changelog section

Once all PRs for the current cycle have been merged and these merges are reflected in the cFS bundle integration-candidate, ensure that all github workflow checks are passing.

Merge local ICs into local main branch

Then, locally checkout each modified submodule's main branch and merge the IC using the following command

git merge integration-candidate --no-ff

and commit-message convention:

Merge IC:CodenameBaseline+devNUMBER, SUBMODULE vBASELINE+devBUILDNUM

- Bulleted list of PR titles
- See <nasa/cFS#BUNDLE_PR_NUM>

Ammend merge commit to add build number changes in Step 4.

Push local ICs to your fork's main branches

Squash all IC commits in your local bundle repo.

Force push bundle repo to nasa integration-candidate

Push local submodule main branches to nasa main branches

Ensure submodules in bundle integration-candidate point to newly pushed submodule main branches in nasa repos.

Verify that all submodule checks are passing

Ensure all PR information is filled out for Bundle Integration candidate

Verify that all Bundle IC checks pass

Click merge button

Fetch new main branch for all submodules

Rebase local submodule integration-candidate onto new main branch; this should make them even.

Push local submodule integration-candidates onto nasa repos

Checkout and pull bundle main branch from origin

Rebase local bundle integration-candidate on top of new bundle main branch.

Push local bundle integration-candidates onto nasa bundle integration-candidate

Clone this wiki locally