Topics on this page

Solution Architecture design and review

BriteCore is a quality-oriented organization, where each engineer strives to deliver the best code that they can. Our goals for delivered code include:

  • Maintainable
  • Extensible
  • Tested
  • Documented

To support these goals, BriteCore has embraced industry-standard best practices.

Goals of code review

The Solution Architecture team creates, maintains, and enforces code standards across implementation projects. Keep these goals in mind when you’re considering contributing to our codebase.

Quality

Ensure only high-quality code reaches production. We want code to be clean and easy to read. It should also be well tested and documented. The more work spent here now means less work spending time fixing it later.

Appropriateness

Make sure the approach to solving the problem is appropriate. Coding can be largely subjective, but some approaches are better than others. If someone is taking an indirect route to solve a problem when a clearer solution exists, helping them identify that lead to higher quality code.

Acceptance criteria fulfilled

Ensure that business requirements for the change are met. Code shouldn’t be changed just for the sake of changing code. Whether it’s adding new functionality, refactoring existing code, or removing unused resources, the code should do what it sets out to do.

Encourage learning

Pull Requests (PR) should serve as a forum for learning. Reviewing a PR gives you a chance to share your knowledge and best practices.

Documentation

PRs create historical documentation. When bugs arise in the future, it’s always helpful to have a PR to reference that explains what was changed and why.

PR workflow overview

The flowchart below covers the basic progression of a PR from its inception to being merged:

Each stage in our workflow, except Merged, is represented by a GitHub label of the form Stage.

Code stage

The Code stage is where all PRs will begin and is also reachable from any stage except Merged. Typically, the next stage for a PR in Code will be Review. The author of a given PR is always responsible for the transition of their PR out of the Code stage.

Entry conditions for code stage

A PR may enter the Code stage when any of the following conditions are true:

  1. A PR is new and/or still under development.
  2. A peer, code reviewer, or QA authority discovers an issue with the code and/or functionality of a PR while it is in the Review stage.
  3. A code reviewer or QA authority discovers an issue with the code/and or functionality of a PR in ANY stage.

Exit conditions for code stage

A PR may leave the Code stage when all the following conditions are satisfied:

  1. The author believes their changes to be complete.
  2. The author has filled out the PR template.
  3. The author either:
    • Successfully refuted the issue(s) which rejected his/her PR back to the Code stage.
    • Resolved any issue(s) which rejected his/her PR to the Code stage and provided evidence of the solution.
    • Is moving their PR to Review of the first time.
  4. All automated checks have succeeded (or failures proven unrelated).
  5. Peer-review has been requested, completed, and approved

Review stage

During the Review stage, peers, code reviewers, and quality assurance (QA) will review the code and functionality introduced by a PR. Peer review and testing is required. Code reviewer approval is required to progress beyond Review. QA approval is requested on an as-needed basis, determined by the code reviewer. Only a code reviewer or QA authority may progress a PR beyond Review. Once a PR has progressed beyond Review, only a code reviewer or QA authority may move it backward in the process.

Entry conditions for review stage

A PR may enter the Review stage when either of the following statements are true:

  1. The previous stage was Code and the Exit Conditions for the Code Stage were met.
  2. The pre-merge checklist revealed a failure to review/test the current changeset.

Exit conditions for review stage

A PR may exit the Review stage when either of the following conditions are met:

  1. A code reviewer and QA authority discover an issue with the code and/or functionality of the PR.
  2. A code reviewer and a QA authority have approved the changes.
  3. Stage 3: Pre-Merge or Stage: 4: Merge label is added.

Review stage progressions

There are three progressions in the Review stage:

  • Code (backwards) return to Stage 1: If there are issues with functionality or bugs, the PR is placed back in code stage with clear documentation on what needs to be fixed.
  • Pre-Marge (forwards) moves to Stage 3: If the PR has passed all checks, reviews, and exit conditions for the review stage, it will move forward to the Pre-Merge stage.
  • Merge (forwards) moves to Stage 4: A PR can move directly to Merge if the following conditions are met:
    • The PR has been approved by a code reviewer and a QA authority.
    • The PR doesn’t meet the Stage 3: Pre-Merge progression requirements (e.g., doesn’t require documentation or targeted releases) above.

Pre-Merge stage

The stage following Review will be either Pre-Merge or Merge. In either case, a PR that has reached this point in the process is unlikely to be rejected backwards, but the right is reserved to do so if the PR doesn’t meet certain conditions (missing documentation, a major shortcoming is discovered prior to a targeted release etc.).

The Pre-Merge stage is a holding stage for PRs, which require some kind of non-code work prior to actually being merged. Examples include targeted releases and documentation.

Entry conditions for Pre-Merge stage

A PR may enter the Pre-Merge stage when the following conditions are met:

  • The PR has been approved by a code reviewer and a QA authority.
  • The PR needs documentation approval.
  • The PR needs a targeted release.

Exit conditions for pre-Merge stage

A PR may exit this stage when the following conditions are met:

  • Any Documentation Required label is complemented by a Documentation Complete label.
  • Any Targeted Release Required label is complemented by a Targeted Release Successful label.
  • A dangerous issue or major shortcoming is discovered prior to any targeted release.
  • All targeted releases are reverted due to issues or shortcomings.
  • Stage: 4: Merge label is added.

Pre-Merge checklist

Pre-Merge Checklist
* [ ] This is not my change.
* [ ] The Testing Checklist has been completed in full.
* [ ] The Review Checklist has been completed in full.
* [ ] Someone (other than the author) has tested this and stated it in this PR AFTER the last commit.
* [ ] Someone (other than the author) has approved this for merge and stated it in this PR AFTER the last commit and AFTER testing was performed.
* [ ] Any prerequisite PRs listed in the description are already merged.
* [ ] All associated testing [S'mores](https://marshmallows.britecorepro.com/list_instances) have been terminated.
* [ ] Soft Releases
  * [ ] No site is configured to soft release this pull request.
  * [ ] If this pull request was soft released, it will be included in the next daily release.

Merge stage

Entry conditions

A PR may enter the Merge stage when either of the following conditions are met:

  • The Exit Conditions for the Pre-Merge stage have been met.
  • The Stage 4: Merge (forwards) progression path requirements were met during the Review stage.

The Merge stage is a queue for PRs which, except for a final audit, have been fully approved for merging.

Exit conditions for Merge stage

A PR may exit the Merge stage when any of the following conditions are met:

  • A dangerous issue or major shortcoming is discovered by a code reviewer or QA authority.
  • The code reviewer filling the Pre-Merge checklist determines steps in the process were skipped.
  • The code reviewer who completes the Pre-merge checklist determines everything to be okay.

A PR implicitly exists in the Merged stage once it has been merged. Any PR in this stage should be in this stage only to prevent cluttering the pipeline of active PRs.

Continuous Delivery

BriteCore uses Continuous Delivery principles and updates web services regularly to ensure ongoing innovation and new technology adoption. In addition to regular, incremental improvement, we are committed to generational updates every five to seven years. Our commitment to innovation helps keep our customer’s systems modern, nimble, and continuously improved.