Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README-internal #149

Merged
merged 10 commits into from
Jul 31, 2024
Merged

Update README-internal #149

Changes from 7 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
990938b
add a note front and center about release and non release commits
jazzsequence Jul 31, 2024
8686091
update language in the differences section
jazzsequence Jul 31, 2024
5202d0f
update ci.yml documentation
jazzsequence Jul 31, 2024
4ec5877
add new section about playwright tests
jazzsequence Jul 31, 2024
4fbc45c
add section about phpcbf action
jazzsequence Jul 31, 2024
e9befba
PHPCBF: Fix coding standards
Jul 31, 2024
cba3016
Merge branch 'default' into update-readme-internal
jazzsequence Jul 31, 2024
8f84172
Update README-internal.md
pwtyler Jul 31, 2024
9015653
alter "commits" to "file changes"
jazzsequence Jul 31, 2024
0d001a3
add clarification about allowing release + non-release changes in the…
jazzsequence Jul 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 10 additions & 3 deletions README-internal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# Working with the WordPress (Composer Managed) upstream

## "Release" and "non-release" commits
The composer-managed upstreams (including Drupal (Composer Managed)) have a idiosyncratic concept of "release" or "normal" commits and "non-release" commits. **Release** commits are those that affect files that are ultimately pushed to the `pantheon-upstreams` repository. This includes the everything that makes the base upstream work and _excludes_ any CI-related files, scripts or tests. **Non-release** commits are those that affect files that are not pushed to the `pantheon-upstreams` repository. This includes CI-related files, scripts, tests, and any other files that are not part of the base upstream.
pwtyler marked this conversation as resolved.
Show resolved Hide resolved

Because we tend to prefer Squash merges on PRs rather than Merge commits, it is vital to separate interests and not combine _release_ and _non-release_ commits in the same PR. Doing so will lead to portions of the PR being dropped when the deploy script is run, leading to a mismatch between the `pantheon-systems` and `pantheon-upstreams` repositories.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Multiple commits in a single PR that keep the division between release and non-release is allowed and encouraged, but should not be squash merged.

This could further be addressed either with a PR template that clarifies a workflow, or a comment out of the existing GH action that comments "Hey I'm going to allow this to happen but don't you dare squash merge"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the comment could get quite noisy on each commit tho , it would have to edit its own comment on subsequent pushes.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I will create an issue to extend the Check Commits action to check commits across the PR, too. In the meantime, I can address in the note.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#150


## Cutting a new release
1. Update CHANGELOG.md. In the past, the copy has been created in consultation with the product owner.
1. Ensure the commit message for the last commit in this release says what we want to have appearing on the
Expand Down Expand Up @@ -29,8 +34,8 @@ There are some atypical development and release procedures in use with this repo
1. Merging a PR to `default` _does not_ create a new release of `pantheon-upstreams/wordpress-composer-managed`. This allows us to batch more than one relatively small change into a single new "release" such that the number of separate update events appearing on customer dashboards is more controlled.

### Differences between `pantheon-upstreams` and `pantheon-systems` repos:
1. Commits modifying any of the following files and directories are omitted from `pantheon-upstreams`: `.circleci`, `devops`, `.github`, `README-internal.md`. This prevents downstream Pantheon sites from being littered with our internal CI configuration, and allows us to enhance CI without generating irrelevant site updates. However, it means **you must not create commits that modify both automation and other files** in the same commit. For this reason **squash commits are discouraged** (as they can contain changes to multiple files).
2. Commit authors appear on the dashboard. For this reason, they are rewritten to `Pantheon Automation <[email protected]>`.
1. Commits modifying any of the following files and directories are omitted from `pantheon-upstreams`: `.circleci`, `devops`, `.github`. This prevents downstream Pantheon sites from being littered with our internal CI configuration, and allows us to enhance CI without generating irrelevant site updates. However, it means **you must not create commits that modify both automation and other files** in the same commit.
2. Commit authors appear on the dashboard. For this reason, they are rewritten to `Pantheon Automation <[email protected]>` by automation.

## Automation demystified
The following workflows run on this repository:
Expand All @@ -39,10 +44,12 @@ The following workflows run on this repository:
* There is only one CircleCI workflow, [`.circleci/config.yml`](.circleci/config.yml). This workflow runs on merge to `release` and handles the deployment of the new release to the `pantheon-upstreams` repositories. See the `devops` folder for the scripts that are run as part of this workflow.

### GitHub Actions
* `ci.yml` - This runs the `Lint and Test` job on pull requests. It runs on PHP 8.x (Roots Bedrock does not support < PHP 8). There are no tests configured, so while `composer test` is run, it does not actually do anything.
* `ci.yml` - This runs the `Lint and Test` job on pull requests. It runs on PHP 8.1-8.3 (Roots Bedrock does not support < PHP 8.1). Playwright tests are run in `playwright.yml` only after `ci.yml` determines that there are no linting issues. Additionally, `ci.yml` adds the commit checking workflow that is normally run on CircleCI to ensure that there are no non-release commits mixed with release commits in a single branch. There are no tests configured in the upstream itself, so while `composer test` is run, it does not actually do anything.
jazzsequence marked this conversation as resolved.
Show resolved Hide resolved
* `composer-diff.yml` - This runs the `Composer Diff` job on pull requests. It compares the `composer.lock` file in the pull request to the `composer.lock` file in the `default` branch. If there are differences, it will comment on the pull request with the differences.
* `sage-test.yml` - This workflow only runs when changes have been made to any of the scripts in `private/scripts` (TODO: if we add more scripts to this directory, we might want to change this behavior to be more specific) or to the workflow file itself. It spins up a new multidev on the `wpcm-sage-install-tests` site on Pantheon and attempts to run `composer install-sage` script. The tests run on `ubuntu-latest` and `macos-latest` environments. (Windows environments need WSL2 to run the script which should broadly be covered by `ubuntu-latest`.)
* `sync-default.yml` - This workflow syncs the `default` branch to `main` in the `pantheon-systems/wordpress-composer-managed` repository. This is used for the [WordPress (Composer Managed) Nightly Canary](https://github.com/pantheon-systems/composer-managed-nightly-canaries). The canary is an automated workflow that spins up a brand new site on Pantheon off of the `default` branch of this repository and runs some basic tests to ensure that the site can be created and that the `composer install` script runs successfully. If the canary site fails to build, an update is posted to the `#cms-ecosystem-repos` channel in Slack.
* `playwright.yml` - This runs a suite of "hello world" style tests on fixture sites on the Pantheon platform using [Playwright](https://playwright.dev/). These tests were adapted from the [Composer Managed Nightly Canaries](https://github.com/pantheon-systems/composer-managed-nightly-canaries) tests originally developed by the Decoupled Kit team. The workflows set up new single site WordPress or subdirectory multisite WordPress sites using the Composer Managed upstream, copy files from the PR over to the new site, and install and run the Playwright tests. In the case of subdomain multisite, a single fixture site is maintained due to the complexity of setting up subdomains in automation.
* `phpcbf.yml` - This runs the `PHP Code Beautifier and Fixer` job on pull requests. It runs on all PRs, commits the changes back to the PR and adds a comment on the pull request if it changed anything. Note that `phpcbf` does not fix _all_ linting issues, and things that `phpcbf` cannot fix will still need to be fixed manually.

## Branch protections and their rationale

Expand Down
Loading