From 112d87c2c89008659635973a241414d224a5e423 Mon Sep 17 00:00:00 2001 From: Ray Estrada Date: Mon, 16 Sep 2024 17:09:21 -0700 Subject: [PATCH 1/2] VOTE-2817 update release documentation --- docs/releases.md | 50 +++++++++++++++++++++++++---------------------- docs/standards.md | 6 ++++++ docs/workflow.md | 16 +++++++-------- 3 files changed, 41 insertions(+), 31 deletions(-) diff --git a/docs/releases.md b/docs/releases.md index fbceec94a..4228536f3 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -1,8 +1,8 @@ # Releases -A **release** is a group of one or more code changes (commits) that have been merged into the `prod` branch, after passing code review and testing (in the DEV and STAGE environments). When referring to a particular release, it's implied that the code to include in that release has been finalized/locked, that the release has been created and that it is either ready to be deployed or has already been deployed to the PROD environment. +A **release** is a group of one or more code changes (commits) that have been merged into the `prod` branch, after passing code review and testing (in the **DEV** and **STAGE** environments). When referring to a particular release, it's implied that the code to include in that release has been finalized/locked, that the release has been created and that it is either ready to be deployed or has already been deployed to the **PROD** environment. - PRs / branches being considered for inclusion in an upcoming release and work that has been merged into either the `dev` or `stage` branch should all be considered "release candidate" code (or work for a particular sprint), but should not be referred to as a "release", to prevent confusion. -- If we say that a particular release has a bug, we generally mean that a bug was found _after_ that release was deployed to PROD (which would need to be addressed in a separate release; see **"Hotfix Releases"** section below for more details). +- If we say that a particular release has a bug, we generally mean that a bug was found _after_ that release was deployed to **PROD** (which would need to be addressed in a separate release; see **"Hotfix Releases"** section below for more details). ## Creating a Release Each release is represented by a [git tag](https://www.atlassian.com/git/tutorials/inspecting-a-repository/git-tag#:~:text=Tags%20are%20ref's%20that%20point,no%20further%20history%20of%20commits.), which points to a particular commit in the `prod` branch's git history – this allows us to be very specific about what the release includes, instead of just saying that we released the latest version of the `dev` branch. Checking out a particular release's git tag will always restore the codebase to the state it was in when that release was created, regardless of any new commits that have since been added to the `dev` branch (or other branches). @@ -21,10 +21,10 @@ MAJOR.MINOR.HOTFIX A new Release Version is generated by taking the version number of the previous release and incrementing one of its version components by 1: - `MAJOR` - incrementing the Major version for a release indicates a major change to the codebase which may not be backwards-compatible. - - We've set the major version to "10" in our first numbered release. If we upgrade to Drupal 11 in the future, we'd increment the major version accordingly; however, this value could be incremented due to other significant architectural changes as well, such as updating the codebase to support a new major version of Drupal. + - We've set the major version to "3" in our first numbered release. If we upgrade to Drupal 11 in the future, we'd increment the major version accordingly to "4"; however, this value could be incremented due to other significant architectural changes as well, such as updating the codebase to support a new major version of USWDS. - `MINOR` - incrementing the Minor version for a release indicates minor changes to the codebase, including feature enhancements, new functionality, bug fixes or other backwards-compatible code. For most releases, this is the only portion of the Release Version that will be incremented. - The Minor version component should be reset to 0 each time the Major version is incremented. -- `HOTFIX` - incrementing the Hotfix version for a release indicates that the release contains one or more hotfixes. A hotfix addresses a critical bug that is identified after a release has already been deployed to the STAGE / PROD environments; these changes are typically committed and deployed to PROD on the same day as the original release, unless the bug is found later. +- `HOTFIX` - incrementing the Hotfix version for a release indicates that the release contains one or more hotfixes. A hotfix addresses a critical bug that is identified after a release has already been deployed to the **STAGE** / **PROD** environments; these changes are typically committed and deployed to **PROD** on the same day as the original release, unless the bug is found later. - The Hotfix version component should be reset to 0 each time a new Release Version is created. Note: the version components above should not include leading zeros. This project's Release Version does not use `-alpha` / `-beta` / `-rc` suffixes. @@ -40,18 +40,18 @@ v4.0.0 - **All PRs proposed for inclusion in an upcoming release should be ready for code review and testing in the week prior, by Thursday (EOD).** This provides time on Friday and Monday for PRs to be tested and modified, if necessary. - All approved PRs / release candidate code should be merged into the `dev` branch by Monday night (or whenever the day before the release deployment is), so that code in `dev` is ready for PRs to be created (for merging into `stage` and `prod` branches) and for the release to be deployed the following day. - Confirm that all code in the `dev` branch has been reviewed/tested and approved to include in the release. -- Release candidate code will typically be deployed to STAGE on a Tuesday, followed by a release deployment to PROD (later that day). +- Release candidate code will typically be deployed to **STAGE** on a Tuesday, followed by a release deployment to **PROD** (later that day). - In some cases, this schedule may be adjusted to account for holidays or team member PTO. - **Deployments should NOT be performed on the following days**, unless absolutely necessary: on a Friday, on a day before a holiday, or on a day when multiple team members are on PTO (or will be on PTO the following day). ### Hotfix Release Schedule -- Hotfix Releases are unscheduled and often deployed to PROD as quickly as possible, once all associated bug fixes have been approved and tested in the STAGE environment. +- Hotfix Releases are unscheduled and often deployed to **PROD** as quickly as possible, once all associated bug fixes have been approved and tested in the **STAGE** environment. - Hotfix Releases that fix major bugs or bugs that affect mission-critical functionality may be deployed the same day as the original deployment. - Hotfix Releases that address less-critical bugs (or bugs that aren't discovered on the same day as the original deployment) may be deployed in the days following the original deployment, based on priority, the client's needs, and other factors. Scheduling a Hotfix Release should follow the same restrictions as detailed above for normal releases. ### Infrastructure Release Schedule -- Infrastructure Releases are unscheduled (like Hotfix Releases) and can be deployed to PROD once all associated bug fixes have been approved and tested in the STAGE environment. +- Infrastructure Releases are unscheduled (like Hotfix Releases) and can be deployed to **PROD** once all associated bug fixes have been approved and tested in the **STAGE** environment. - Scheduling an Infrastructure Release should follow the same restrictions as detailed above for normal releases. @@ -61,36 +61,40 @@ The release history for this project is documented on the repo's Github page (un ## Releases require deployments ### Freezing code for the release -Once the the "release candidate" code for an upcoming release has been approved and merged into the `dev` branch, that branch should be frozen (no new commits or PRs merged in) until it has been merged into the `stage` branch. If possible, this code freeze / merge should occur 2 or 3 days prior to the PROD deployment, so there is adequate time to properly test the release candidate code in the STAGE environment. +At the end of the active sprint a "release candidate" PR is create from approved and merged work from the `dev` branch with the target branch set to `stage`, that branch should be frozen (no new commits or PRs merged in) until it has been merged. If possible, this code freeze / merge should occur 2 or 3 days prior to the **PROD** deployment, so there is adequate time to properly test the release candidate code in the **STAGE** environment. ### Deploying to STAGE -Before a release can be created and deployed to the PROD environment, the approved "release candidate" code must be merged from the `dev` branch into the `stage` branch (using a PR), then deployed to the STAGE environment and tested there. +**Merge strategy:** `Create a merge commit` This strategy maintains the history and commit ids in all environment branches. -If a bug is found on STAGE (after deploying release candidate code there), it should be handled as a standard bug fix -- this is NOT considered a "hotfix", however (see **"Hotfix Releases"** section below). Once the bug has been fixed and merged into the `dev` branch, it may be approved for inclusion in the upcoming release, then merged into `stage` and redeployed to the State environment for testing. -- If there isn't enough time to address a bug or deploy/test an approved bug fix on STAGE, then the original PR (where the bug was introduced) should be excluded from the upcoming release and included in a future one instead. +Before a release can be created and deployed to the **PROD** environment, the approved "release candidate" PR must be merged from the `dev` branch into the `stage` branch, then deployed to the **STAGE** environment and tested there. + +If a bug is discovered on **STAGE** (after deploying "release candidate" code), it should be handled as a standard bug fix -- this is NOT considered a "hotfix" (see **"Hotfix Releases"** section below). Once the bug has been fixed and merged into the `dev` branch, it may be approved and merged into `stage` branch for inclusion in the "release candidate" and deployed to the **STAGE** environment for testing. +- If there isn't enough time to address a bug or deploy/test an approved bug fix on **STAGE**, then the original PR (where the bug was introduced) should be excluded from the upcoming release and included in a future one instead with the fix. ### Deploying to PROD -Once all release candidate code in the `stage` branch has been successfully tested in the STAGE environment, the `stage` branch should be merged into the `prod` branch. At this point, a git tag can be created for the new release (using an appropriate Version Number) and this git tag can be deployed to the PROD environment. After all work in the release has been tested in PROD, the release is considered complete. -- Any bugs found on PROD, following deployment (whether related to the release or not), must be addressed with a separate release (with its own Release Number) -- for critical bugs, a Hotfix release would be created and deployed to PROD asap; less-critical bugs could either be handled in a Hotfix release or in a future release. In either case, the original release should not be modified or recreated to include a bug fix / hotfix. -- Releases represent what has been deployed to the PROD environment, so there should be a corresponding release for every PROD deployment (even those involving a minor code fix). +**Merge strategy:** `Create a merge commit` This strategy maintains the history and commit ids in all environment branches. + +Once the "release candidate" in the `stage` branch has been successfully tested in the **STAGE** environment, a "release" PR is created to merge the `stage` branch into the `prod` branch. Once the "release" is approved and merged, a Git release and tag can be created capturing the release (using **"Release Version Convention"** found in this doc) and this git tag can be deployed to the **PROD** environment. After all work in the release has been tested in **PROD**, the release is considered complete. +- Any bugs found on **PROD**, following deployment (whether related to the release or not), must be addressed with a separate release (with its own Release Number) -- for critical bugs, a Hotfix release would be initiated; less-critical bugs could either be handled in a Hotfix release or in a future release. In either case, the original release should not be modified or recreated to include a bug fix / hotfix. +- Releases represent what has been deployed to the **PROD** environment, so there should be a corresponding release for every **PROD** deployment (even those involving a minor code fix). ## Hotfix Releases -After deploying a normal release to the PROD site, it's possible that a bug (or multiple bugs) will be discovered by the project team or the client; this may occur either on the day of the deployment or in the days that follow. If it's decided that the bug affects mission-critical functionality or otherwise requires an immediate fix, a hotfix should be created and deployed to PROD as soon as possible, as a **Hotfix Release**. -- A Hotfix Release is a special type of release that requires unscheduled deployments to the STAGE and PROD environments. For additional guidance on when to deploy a Hotfix Release, see the **"Hotfix Release Schedule"** section above. -- A Hotfix Release should only contain hotfixes for bugs found on the PROD site. -- If the bug found on PROD is not urgent enough to necessitate an immediate fix (and can be addressed in the next scheduled release cycle), the fix for this bug is NOT considered a hotfix. -- If a bug is found after deploying "release candidate" code to Stage, this should be fixed and merged into the `dev` branch, then deployed to STAGE again; this type of bug fix is NOT considered a hotfix (and should not be handled as a Hotfix Release). +After deploying a normal release to the **PROD** site, it's possible that a bug (or multiple bugs) will be discovered by the project team or the client; this may occur either on the day of the deployment or in the days that follow. If it's decided that the bug affects mission-critical functionality or otherwise requires an immediate fix, a hotfix should be created and deployed to **PROD** as soon as possible, as a **Hotfix Release**. +- A Hotfix Release is a special type of release that requires unscheduled deployments to the **STAGE** and **PROD** environments. For additional guidance on when to deploy a Hotfix Release, see the **"Hotfix Release Schedule"** section above. +- A Hotfix Release should only contain hotfixes for bugs found on the **PROD** site. +- If the bug found on **PROD** is not urgent enough to necessitate an immediate fix (and can be addressed in the next scheduled release cycle), the fix for this bug is NOT considered a hotfix. +- If a bug is found after deploying "release candidate" code to **STAGE**, this should be fixed and merged into the `dev` branch, then deployed to **STAGE** again; this type of bug fix is NOT considered a hotfix (and should not be handled as a Hotfix Release). ### To create a Hotfix Release: - All hotfix code should be submitted as PR(s) against the `stage` branch. Because we want to avoid deploying non-hotfix code in the Hotfix Release, hotfix PRs should NOT be created against the `dev` branch. -- Once all hotfix PRs have been merged into `stage`, they should be deployed to the STAGE environment and tested there. -- After all hotfixes have been successfully tested on STAGE: +- Once all hotfix PRs have been merged into `stage` branch, they should be deployed to the **STAGE** environment and tested there. +- After all hotfixes have been successfully tested on **STAGE**: - A single hotfix PR should be created to merge the `stage` branch into the `prod` branch. - - An additional PR should be created to merge all hotfixes (from `stage`) back into the `dev` branch. + - An additional PR should be created to merge all hotfixes from `stage` branch back into the `dev` branch. ## Infrastructure Releases Infrastructure-related code changes modify configuration or behavior outside of the application layer, generally involving specific environments or a deployment pipeline. If these changes need to be deployed before the next scheduled release cycle, they can be handled as an **Infrastructure Release**, which is very similar to a Hotfix Release. -- An Infrastructure Release is a special type of release that requires unscheduled deployments to the STAGE and PROD environments. For additional guidance on when to deploy a Hotfix Release, see the **"Infrastructure Release Schedule"** section above. +- An Infrastructure Release is a special type of release that requires unscheduled deployments to the **STAGE** and **PROD** environments. For additional guidance on when to deploy a Hotfix Release, see the **"Infrastructure Release Schedule"** section above. - As with a Hotfix Release, the release candidate code for an Infrastructure Release should be independent of any active development happening in the `dev` branch and should only include infrastrucure-related code changes. - For additional guidance on when to deploy a Hotfix Release, see the **"Infrastructure Release Schedule"** section above. diff --git a/docs/standards.md b/docs/standards.md index 0ab64a661..b650d9120 100644 --- a/docs/standards.md +++ b/docs/standards.md @@ -42,3 +42,9 @@ Please ensure you have addressed all concerns below before marking a PR "ready f - Check basic logic of the code. - Check for coding best practices (to the best of your ability). - Check for insufficiently commented code. + +## Merge strategy guidance +- PRs merged into `dev` branch should use the "Squash and merge" method, ensuring that every commit starts with a ticket number followed by a brief description of changes. + - **Special case**: A merge from the `stage` branch to the `dev` branch needs to maintain history and should use the "Create a merge commit" method instead. +- PRs merged into `stage` branch should use the "Create a merge commit" method, this is critical for maintaining commit history and ids in all environment branches. +- PRs merged into `prod` branch should also use the "Create a merge commit" method. diff --git a/docs/workflow.md b/docs/workflow.md index 89c435b92..bc59b45d4 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -13,9 +13,9 @@ These are the workflow guidelines that are being used to develop and maintain th 8. Meanwhile, automated tests run in the pipeline 9. Code Reviewer approves PR or requests revisions 10. QA Engineer approves PR or requests revisions -11. If the PR is approved, the designated code maintainer merges the PR into the target branch +11. If the PR is approved, the designated code maintainer merges the PR into the target branch using the appropriate [merge strategy](standards.md) 12. Code is deployed to DEV for testing in the cloud.gov environment -13. Approved code marked ready to release will be deployed to STAGE for any final UAT +13. Approved code marked ready to release will be deployed to STAGE for final testing and approval 15. Work in STAGE will be deployed to PROD in the next scheduled release as a [standard release](releases.md) ## Hotfix development task @@ -29,9 +29,9 @@ These are the workflow guidelines that are being used to develop and maintain th 8. Meanwhile, automated tests run in the pipeline 9. Code Reviewer approves PR or requests revisions 10. QA Engineer approves PR or requests revisions -11. If the PR is approved, the designated code maintainer merges the PR into the target branch -12. Approved code marked ready to release will be deployed to STAGE for any final UAT -13. Designated code maintainer creates a PR from STAGE to DEV to sync changes down +11. If the PR is approved, the designated code maintainer merges the PR into the target branch using the appropriate [merge strategy](standards.md) +12. Approved code marked ready to release will be deployed to STAGE for final testing and approval +13. Designated code maintainer creates a PR from STAGE to DEV to sync changes down using appropriate [merge strategy](standards.md) 14. Work in STAGE is deployed to PROD as a [hotfix release](releases.md) ## Infrastructure development task @@ -44,8 +44,8 @@ These are the workflow guidelines that are being used to develop and maintain th 7. Meanwhile, automated tests run in the pipeline 8. Code Reviewer approves PR or requests revisions 9. QA Engineer approves PR or requests revisions -10. If the PR is approved, the designated code maintainer merges the PR into the target branch +10. If the PR is approved, the designated code maintainer merges the PR into the target branch using appropriate [merge strategy](standards.md) 11. Code is deployed to DEVOPS for testing in the cloud.gov environment -12. Approved code deemed ready to release will be deployed to STAGE for any final UAT -13. Designated code maintainer creates a PR from STAGE to DEV to sync changes down +12. Approved code deemed ready to release will be deployed to STAGE for final testing and approval +13. Designated code maintainer creates a PR from STAGE to DEV to sync changes down using appropriate [merge strategy](standards.md) 14. Work in STAGE will be deployed to PROD as a [infrastructure release](releases.md) From 41b39d386841e33d0e80963ee49cd3fef1e43fc5 Mon Sep 17 00:00:00 2001 From: Ray Estrada Date: Wed, 18 Sep 2024 12:24:02 -0700 Subject: [PATCH 2/2] VOTE-2689 update docs for launched CMS --- docs/README.md | 12 ++++++------ docs/backend.md | 6 ------ docs/frontend.md | 16 ++++++++++------ docs/testing.md | 1 + 4 files changed, 17 insertions(+), 18 deletions(-) diff --git a/docs/README.md b/docs/README.md index 3e90189b4..9837f17ab 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,12 +3,12 @@ ## Environments and git branches List of development environments and their equivalent git branches. -| **Public (static)** | **CMS** | **Cloud.gov environments** | **Git branch** | **Use case** | -|---------------------|--------------------|----------------------------|----------------|----------------------------------------------------------| -| ssg-dev.vote.gov | cms-dev.vote.gov | vote-drupal-dev | dev | App work that is ready for testing in cloud.gov | -| ssg-test.vote.gov | cms-test.vote.gov | vote-drupal-test | test | Pipeline development work ready for testing in cloud.gov | -| staging.vote.gov | cms-stage.vote.gov | vote-drupal-stage | stage | All work that is ready for release/UAT testing | -| vote.gov | cms.vote.gov | vote-drupal-prod | prod | All work that is approved and released | +| **Static** | **CMS** | **Cloud.gov environments** | **Git branch** | **Use case** | +|-------------------|--------------------|----------------------------|----------------|----------------------------------------------------------| +| ssg-dev.vote.gov | cms-dev.vote.gov | vote-drupal-dev | dev | App work that is ready for testing in cloud.gov | +| ssg-test.vote.gov | cms-test.vote.gov | vote-drupal-test | test | Pipeline development work ready for testing in cloud.gov | +| staging.vote.gov | cms-stage.vote.gov | vote-drupal-stage | stage | All work that is ready for release/UAT testing | +| vote.gov | cms.vote.gov | vote-drupal-prod | prod | All work that is approved and released | ## Table of Contents - [Git standards](standards.md) diff --git a/docs/backend.md b/docs/backend.md index 79502745f..4a3a27815 100644 --- a/docs/backend.md +++ b/docs/backend.md @@ -73,18 +73,12 @@ A CKEditor5 Embedded Content plugin that provides a means for embedding a Touchp #### USAgov login Adds the ability to disable the default Drupal login form and replace with a button to log in via SSO. -#### Vote migrate -Migration scripts to run to import translations from GitHub pages.cloud.gov site. - #### Vote utility Provides custom token for use in pathauto settings. Adds the ability to limit the storage of block content revisions. Stores the source po files for importing string translations in the system. ## Module Patches Review the details in composer.json file under `extra.patches` additionally look at the `/patches/` directory at the root. These patches need to be re-evaluated when the original module gets updated to determine if the work has been included in the latest release or if the patch needs to be rerolled. -## Migration -Instructions for updating and running migration scripts. - ## Database - Mysql The site utilizes Mysql for its database. diff --git a/docs/frontend.md b/docs/frontend.md index 69f0d4cb8..d3627da2b 100644 --- a/docs/frontend.md +++ b/docs/frontend.md @@ -5,8 +5,8 @@ This site is built using Drupal and Tome with a USWDS theme. These commands should be run inside web/themes/custom/votegov | **Command** | **Use case** | |------------------|-----------------------------------------------------------------------------------| -| `npm run build` | Aggregates, compiles and minifies frontend assets into the dist directory | -| `npm run dev` | Starts browsersync, watches for scss/js/twig file changes and compiles frontend assets into the dist directory | +| `npm run build` | Aggregates, compiles and minifies frontend assets into the dist directory for deployment | +| `npm run dev` | Starts watching for changes to scss/js/twig files and compiles frontend assets into the dist directory | ## Theme file structure ``` @@ -21,9 +21,11 @@ web/ ├── dist ├── fonts ├── img + ├── json ├── php-includes - ├── js - ├── sass + └── src/ + ├── js + └── sass └── templates ``` @@ -33,11 +35,13 @@ web/ **img** - All favicons and logos that compile into dist +**json** - Number translation mapping json for frontend utility replacement + **php-includes** - Preprocess and theme functions organized by use type -**js** - Javascript files that compile into dist +**src/js** - Javascript files that compile into dist -**sass** - SCSS files that compile into dist +**src/sass** - SCSS files that compile into dist **templates** - Vote.gov theme templates and template overrides. Templates inside the /templates/partial directory are being included or extended by other templates. diff --git a/docs/testing.md b/docs/testing.md index c0d07ac7b..2da0b814e 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -25,6 +25,7 @@ There are multiple custom commands that will both create a user and also delete Here are the following users/role - site admin +- site builder - content manager - content editor