Skip to content

Commit 8c5669b

Browse files
RajdeepcRajdeepc
authored
Merge branch 'main' into castastrophe/chore-lint-staged-tooling
2 parents f7d7d8f + ba4e9bd commit 8c5669b

15 files changed

+999
-157
lines changed

‎.changeset/README.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,12 @@ A typical changeset file looks like this:
3939
'@spectrum-web-components/theme': patch
4040
---
4141
42-
Added new variant to button component and fixed theme compatibility issues
42+
- **Added**: Added new variant `tertiary` to `<sp-button>` component [#9999](https://github.com/adobe/spectrum-web-components/pull/9999)
43+
- **Fixed**: Fixed `<sp-theme>` theme compatibility issues [#10000](https://github.com/adobe/spectrum-web-components/pull/10000)
4344
```
4445
46+
For our guidelines on writing changesets, see [our writing changesets guide](https://opensource.adobe.com/spectrum-web-components/guides/writing-changesets/).
47+
4548
## Common Questions
4649
4750
We have a quick list of common questions to get you started engaging with this project in

‎.github/PULL_REQUEST_TEMPLATE.md

+12-8
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
1-
<!--- Provide a general summary of your changes in the Title above -->
2-
<!--- PR titles should follow conventional commit and should include commit type as defined in in the PULL_REQUESTS guide -->
3-
<!--- Conventional commit docs can be referenced here: https://www.conventionalcommits.org/en/v1.0.0/#summary -->
1+
<!---
2+
- Following conventional commit format, provide a general summary of your changes in the title above.
3+
- Acceptable commit types in order of severity (high to low): feat, fix, docs, style, chore, perf, and test. Commit types are defined in PULL_REQUESTS.md.
4+
- For example,`type(component): general summary`
5+
-->
46

57
## Description
68

@@ -42,14 +44,16 @@
4244
- [ ] Includes thoughtfully written changeset if changes suggested include `patch`, `minor`, or `major` features
4345
- [ ] Automated tests cover all use cases and follow best practices for writing
4446
- [ ] Validated on all supported browsers
45-
- [ ] All VRTs are approved before author can update Golden Hash
47+
- [ ] All VRTs are approved before the author can update Golden Hash
4648

4749
### Manual review test cases
4850

49-
<!--- For the author, please describe in detail what reviewers should test. -->
50-
<!--- Include links and manual steps for how the reviewer should go through to verify your changes. -->
51-
<!--- Be sure to include manual tests for all areas of the codebase that might be affected. Any components that use this for a dependency should be cross-checked for regressions. -->
52-
<!--- For example, changes to Menu Item will effect Picker, Menu, and Action Menu. -->
51+
<!---
52+
- For the author, please describe in detail what reviewers should test.
53+
- Include links and manual steps for how the reviewer should go through to verify your changes.
54+
- Be sure to include all areas of the codebase that might be affected. Any components that use these changes for a dependency should be cross-checked for regressions.
55+
- For example, changes to Menu Item will affect Picker, Menu, and Action Menu.
56+
-->
5357

5458
- [ ] _Descriptive Test Statement_
5559

‎.github/workflows/pr-update.yml

+4-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
name: Update PRs
22

3-
on: workflow_dispatch
3+
on:
4+
pull_request:
5+
types: [labeled, auto_merge_enabled]
46

57
jobs:
68
autoupdate:
@@ -23,4 +25,4 @@ jobs:
2325
include_drafts: false
2426
limit: 50
2527
exclude_labels: blocked,wip
26-
include_labels: in-review,ready-for-merge
28+
include_labels: auto-update,ready-for-merge

‎.github/workflows/publish.yml

+2-2
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@ jobs:
1010
site-build:
1111
name: Build & publish site
1212
runs-on: ubuntu-latest
13-
# Run the job if manually triggered or if the commit message includes '#publish' & the check suite has passed
14-
if: github.event_name == 'workflow_dispatch' || contains(github.event.head_commit.message, '#publish')
13+
# Run the job if manually triggered or if the commit message includes '#publish' & the check suite has passed or if the commit message includes 'docs' and the check suite has passed
14+
if: github.event_name == 'workflow_dispatch' || contains(github.event.head_commit.message, '#publish') || contains(github.event.head_commit.message, 'docs')
1515
steps:
1616
- name: Checkout PR branch
1717
uses: actions/checkout@v4

‎CONTRIBUTING.md

+1-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
1-
<!-- omit from toc -->
2-
3-
# Contributing best practices
1+
# Contributing best practices <!-- omit from toc -->
42

53
Welcome! We're excited you're interested in improving Spectrum Web Components. Whether you're reporting bugs, adding new features, writing documentation, or helping other users, your contributions make this project better for everyone.
64

‎PULL_REQUESTS.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
1-
<!-- omit from toc -->
2-
3-
# Pull request best practices
1+
# Pull request best practices <!-- omit from toc -->
42

53
This document outlines our team's expectations and best practices for creating, reviewing, and merging pull requests for Spectrum Web Components.
64

@@ -93,6 +91,7 @@ Incomplete templates may delay the review process.
9391
## Labels and their meanings
9492

9593
- `ready-for-review`: PR is ready for maintainer review
94+
- `ready-for-merge`: PR has two approvals and all tests pass. This label will keep the base of the PR up-to-date with main until it's merged.
9695
- `WIP`: PR is still being worked on, not ready for review
9796
- `blocked`: PR is blocked for some reason i.e. another PR needs to go in first
9897
- `needs-tests`: PR is missing necessary tests
@@ -105,6 +104,7 @@ Incomplete templates may delay the review process.
105104
- `on-hold`: PR needs more discussion.
106105
- `Spectrum CSS`: An issue or pull request specific to the CSS being used by components.
107106
- `Component: [Name]`: PR effects this component
107+
- `auto-update`: Keep the base of the PR up-to-date with main automatically if there are no conflicts.
108108

109109
Apply labels promptly to help maintainers prioritize and manage the review queue.
110110

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ The project will be linted on a pre-commit hook, but you can also run the lint s
102102

103103
### Dependency linting
104104

105-
There are downstream issues that can arise from multiple packages in this mono-repo using dependencies with mismatched version strings. By default, changesets will bump version numbers of internal dependencies when the various packages are published and the depended version is pointing to the latest release, which can help to mitigate this issue. Running `yarn lint:versions` will check that all version strings for each dependency match across the repo.
105+
There are downstream issues that can arise from multiple packages in this mono-repo using dependencies with mismatched version strings. By default, [changesets](https://opensource.adobe.com/spectrum-web-components/guides/writing-changesets/) will bump version numbers of internal dependencies when the various packages are published and the depended version is pointing to the latest release, which can help to mitigate this issue. Running `yarn lint:versions` will check that all version strings for each dependency match across the repo.
106106

107107
`yarn list:versions --fix` will modify the `package.json` files, updating all dependencies to the latest version available in the library — _a potentially dangerous operation_. If this is what you want to do when `yarn lint:versions` discovers mismatched versions, this step can greatly reduce the amount of work to achieve matching version numbers.
108108

‎RELEASE_PROCESS.md

+119-26
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,129 @@
1-
# Releasing a new version of Spectrum Web Components
1+
# Releasing a new version of Spectrum Web Components <!-- omit from toc -->
22

3-
Users with permissions in the `@spectrum-web-components` organization on NPM can follow the following steps to create and publish a new version.
3+
Users with permissions in the `@spectrum-web-components` organization on NPM can follow these steps to create and publish a new version.
44

5-
1. Merge all pull requests to be included in the release and wait for the `main` branch to show that it has completed the required CI jobs.
6-
2. `git checkout main && git fetch && git pull && git clean -dfX`
7-
3. Run `nvm use` assumes a Node Version Manager install, and confirm your on an operable version of Node.
8-
4. `yarn install && yarn build` to install all dependencies and build the pre-processed assets for publication.
9-
5. `npm whoami` ensure that you are logged in with the user account for the public NPM registry
10-
6. `yarn changeset-publish`
11-
7. Scan the version summary for any unexpected changes.
12-
- Changes to the _major_ versions number are likely to point to undesired version numbers.
13-
- Changes to the _minor_ or _feature_ version number should be confirmed as correct against the changes that have been made since the last release.
14-
8. `Y` to confirm.
15-
9. Enter one time password for npm.
16-
10. After the SWC packages are released, the React Wrapper packages will be generated. This multi-phase approach ensure that the wrapped packages share the same version as the standard packages.
17-
11. Scan the version summary for any unexpected changes.
18-
- The versions _should_ be the same as those that just we applied to their matched SWC packages.
19-
- Changes to the _major_ versions number are likely to point to undesired version numbers.
20-
- Changes to the _minor_ or _feature_ version number should be confirmed as correct against the changes that have been made since the last release.
21-
12. `Y` to confirm.
22-
13. Enter a new one time password for npm.
5+
- [Prerequisites](#prerequisites)
6+
- [Main successfully builds](#main-successfully-builds)
7+
- [The correct version of Node is installed](#the-correct-version-of-node-is-installed)
8+
- [Using Node Version Manager](#using-node-version-manager)
9+
- [Manually checking](#manually-checking)
10+
- [Troubleshooting](#troubleshooting)
11+
- [Github Token is set up](#github-token-is-set-up)
12+
- [Generate a Github token](#generate-a-github-token)
13+
- [Logged in to NPM](#logged-in-to-npm)
14+
- [NPM 2FA authenticator app](#npm-2fa-authenticator-app)
15+
- [Releasing to NPM — the good stuff](#releasing-to-npm--the-good-stuff)
16+
- [Troubleshooting](#troubleshooting-1)
17+
- [Publishing the documentation site manually](#publishing-the-documentation-site-manually)
18+
- [From GitHub](#from-github)
19+
- [From the terminal](#from-the-terminal)
20+
- [References](#references)
2321

24-
The docs site will publish automatically if the `#publish` string is included in the commit message and the check suite runs successfully.
22+
## Prerequisites
2523

26-
If publishing fails with an error, check the [list of tags](https://github.com/adobe/spectrum-web-components/tags) to see if new tags have been released for your publishing attempt. If they were, run `yarn changeset-publish` again.
24+
### Main successfully builds
2725

28-
## Publishing the docs site manually
26+
Merge all pull requests to be included in the release, and wait for the `main` branch to show that it has completed the required Circle CI jobs.
2927

30-
Navigate to SWC's [Actions](https://github.com/adobe/spectrum-web-components/actions) and click the `Build & publish site` link under the _Workflows_ heading.
28+
Check [Circle Ci build for `main`](https://app.circleci.com/pipelines/github/adobe/spectrum-web-components?branch=main) shows a `success` status. 1. If it failed, click `rerun` dropdown and select `rerun from failed`. 2. If it continues to fail, investigate further until you can successfully get the `main` branch building.
3129

32-
At the top of the table you will see a `Run workflow` dropdown; click that and run it from the `main` branch.
30+
---
3331

34-
[Running manual workflows](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow), GitHub documentation
32+
### The correct version of Node is installed
33+
34+
This is important to confirm before next step because differing node versions will cause build issues.
35+
36+
#### Using Node Version Manager
37+
38+
Run `nvm use` (assumes a Node Version Manager install), and confirm you’re on an operable version of Node.
39+
40+
#### Manually checking
41+
42+
1. Run `node --version` to see what version you have installed
43+
2. Check `.nvmrc` for node version requirements.
44+
3. If the versions don't match, run `node install [version]`
45+
46+
#### Troubleshooting
47+
48+
If you need to install the correct yarn version and/or have issues with `yarn` command not being recognized, run `corepack enabled`. Yarn 4 uses corepack and needs to be enabled to access the commands.
49+
50+
---
51+
52+
### Github Token is set up
53+
54+
Check you have a GitHub token set up, run `echo $GITHUB_TOKEN`.
55+
56+
#### Generate a Github token
57+
58+
1. If you do not have one, set it up in [Github settings > Developer settings > Personal access tokens](https://github.com/settings/personal-access-tokens)
59+
1. Create a classic token
60+
- Note: SWC changeset release token
61+
- Set the expiration to a year or less
62+
- Scopes:
63+
- `repo (all)`
64+
- `read:user`
65+
2. Add generated token to `~/.zshrc` with `export GITHUB_TOKEN='token'`
66+
- Make sure there isn't another export with the same name
67+
3. Close your terminal to reset your profile, open terminal back up
68+
69+
---
70+
71+
### Logged in to NPM
72+
73+
Run `npm whoami` ensure that you are logged in with the user account for the public NPM registry.
74+
75+
If not logged in, run `npm login` to sign in to your account.
76+
77+
---
78+
79+
### NPM 2FA authenticator app
80+
81+
1. Go to `Account Settings` on NPM
82+
2. Click `Modify 2FA` in the Two-Factor Authentication section
83+
3. Follow the instructions to configure the authenticator app (i.e. Google Authenticator) of your choice
84+
1. Should be able generate a 6-digit password that updates regularly
85+
86+
---
87+
88+
## Releasing to NPM — the good stuff
89+
90+
1. Run `git checkout main && git fetch && git pull && git clean -dfX` to ensure you are working with the latest code
91+
2. Run `yarn install && yarn build` to install all dependencies and build the pre-processed assets for publication.
92+
1. Confirm no files were updated or modified
93+
3. Scan the version summary for any unexpected changes
94+
1. In your IDE search `': major` , `': minor`, `': patch` , based on the results in the order of this search list, the highest level takes precedence
95+
1. exclude files: `.changeset/README.md`
96+
4. Open your authenticator app to have it ready
97+
5. Run`yarn changeset-publish`
98+
6. Enter the one-time password from your authenticator for NPM.
99+
1. Wait for a fresh password; a stale timer might cause issues.
100+
7. After the SWC packages are released, the React Wrapper packages will be generated.
101+
1. This multi-phase approach ensures that the wrapped packages share the same version as the standard packages.
102+
8. Enter a new one-time password from your authenticator for NPM.
103+
9. The `yarn changeset-publish` command will automatically commit the changes to main with a commit message of `chore: release new versions #publish`
104+
1. The docs site will publish automatically if the `#publish` string is included in the commit message and the check suite runs successfully.
105+
10. Confirm the build on `main` passes
106+
107+
### Troubleshooting
108+
109+
If publishing fails with an error:
110+
111+
- Check the [list of tags](https://github.com/adobe/spectrum-web-components/tags) to see if new tags have been released for your publishing attempt.
112+
- If they were, run `yarn changeset-publish` again.
113+
114+
---
115+
116+
## Publishing the documentation site manually
117+
118+
### From GitHub
119+
120+
1. Navigate to SWC's [Actions](https://github.com/adobe/spectrum-web-components/actions) and click the `Site publish` workflow.
121+
2. At the top of the table, click the `Run workflow` dropdown — Use workflow from `main` branch, and click the `run workflow` button.
122+
123+
### From the terminal
35124

36125
If you have the [GitHub CLI](https://cli.github.com) installed, you can alternatively run `gh workflow run publish.yml --ref main` from the command line.
126+
127+
### References
128+
129+
[Running manual workflows](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow), GitHub documentation

0 commit comments

Comments
 (0)