diff --git a/README.md b/README.md index 57ebecbd..18aadab8 100644 --- a/README.md +++ b/README.md @@ -26,12 +26,12 @@ Check the [FAQ](#faq) fro more on these. - [Verify plugin package](#verify-plugin-package) - [Upgrading a v2 plugin](#upgrading-a-v2-plugin) - [Upgrade help in v2 Studio](#upgrade-help-in-v2-studio) -- [Inject config into existing v3 plugin](#inject-config-into-existing-v3) +- [Inject config into existing v3 plugin](#inject-config-into-existing-package) - [Testing a plugin in Sanity Studio](#testing-a-plugin-in-sanity-studio) - [Upgrading from plugin-kit 1.x](#upgrade-from-v1x-to-v2) - [FAQ](#faq) aka "Do I _have_ to use this plugin-kit?" aka No - [Configuration reference](#configuration-reference) -- [Developing plugin-kit](#developing-plugin-kit) +- [Developing plugin-kit](#develop-plugin-kit) ## Installation @@ -140,7 +140,10 @@ Each check will explain why it is needed, steps to fix it and how it can be indi ### What it is _not_ -`verify-package` is _not_ a codemod tool (yet). It will only check files and recommended settings: it will not change any files. +`verify-package` is _not_ a codemod tool. It will only check files and recommended settings: it will not change any files. + +Consider using `npx @sanity/plugin-kit inject` if you want to add recommended V3 plugin configuration automatically. +See the [Inject docs](#inject-config-into-existing-package) for more on this. ### Upgrading a v2 plugin @@ -178,16 +181,29 @@ npx @sanity/plugin-kit verify-package --studio --single This will only output the first validation that fails. Useful when working through the list of issues by fixing and rerunning the command. -### Inject config into existing v3 +## Inject config into existing package -Consult the inject command CLI help: +``` +npx @sanity/plugin-kit inject +``` +will inject recommended V3 plugin package boilerplate into an existing plugin. +Be sure to commit any local changes before running this command, so you can easily revert anything +you dont want. +Consult the inject command CLI help: ``` npx @sanity/plugin-kit inject --help ``` for up-to-date specifics. +### Presets + +The inject command can do more work by adding presets. Consult the individual preset docs for details: + +* [semver-workflow](./docs/semver-workflow.md) - Add an opinionated Github workflow to automate NPM releases +* [renovatebot](./docs/renovatebot.md) - Add opinionated Renovatebot config to make dependency management a breeze + ## Testing a plugin in Sanity Studio Ensure you have the following script setup in package.json: @@ -465,7 +481,7 @@ npm run test -- test/verify-package.test.ts npm run test -- test/verify-package.test.ts --snapshot ``` -## Developing plugin kit +## Develop plugin-kit ### Release new version diff --git a/docs/assets/semver-workflow-example.png b/docs/assets/semver-workflow-example.png new file mode 100644 index 00000000..f26c6d76 Binary files /dev/null and b/docs/assets/semver-workflow-example.png differ diff --git a/docs/renovatebot.md b/docs/renovatebot.md index f7202ad2..414dd259 100644 --- a/docs/renovatebot.md +++ b/docs/renovatebot.md @@ -1,10 +1,12 @@ # Preset: renovatebot -## Manual steps after inject +## Usage -After injection, Renovate bot must be enabled for the repo on Github. +### Inject into existing package +`npx @sanity/plugin-kit inject --preset-only --preset renovatebot` -This can be done by adding the repo to Github Renovatebot app allow-list. +### Use to init plugin +`npx @sanity/plugin-kit init --preset renovatebot ` ## What does it do? @@ -12,3 +14,10 @@ Sets up the repo - Adds Sanity dependabot preset dependency. - Adds `renovate.json` to configure the above dependency for Renovatebot + +## Manual steps after inject + +After injection, Renovate bot must be enabled for the repo on Github. + +This can be done by adding the repo to Github Renovatebot app allow-list. + diff --git a/docs/semver-workflow.md b/docs/semver-workflow.md index c7069ec9..64913eef 100644 --- a/docs/semver-workflow.md +++ b/docs/semver-workflow.md @@ -1,7 +1,36 @@ # Preset: semver-workflow -Add opinionated config and dependencies used by the Ecosystem team on Sanity to develop using -semantic-release driven workflow on Github for Sanity v3 plugins. +## Usage + +### Inject into existing package +`npx @sanity/plugin-kit inject --preset-only --preset semver-workflow` + +### Use to init plugin +`npx @sanity/plugin-kit init --preset semver-workflow ` + +## What does it do? + +Adds opinionated config and dependencies used by the Ecosystem team on Sanity, to develop using +semantic-release driven workflow on Github. + +![Github workflow](assets/semver-workflow-example.png) + +This preset: + +- adds [husky](https://github.com/typicode/husky) for pre-commit hooks to ensure that: + - all commits follow [conventional-commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) format + - all files in a commit pass eslint +- [semantic-release](https://semantic-release.gitbook.io/semantic-release/) automation for npm publish + - automates Github releases + - updates package version based on conventional-commits + - updates CHANGELOG.md +- [GitHub workflow](https://docs.github.com/en/actions/using-workflows) (Action) that + - does continuous integration + - has publish-on-demand support which delegates to semantic-release +- updates README.md with some standard texts, if missing + +Keep in mind that this setup is tailored to the needs of the Ecosystem team at Sanity. +Feel free to modify any and all files injected by the preset, or use it as a basis for creating your own workflow. ## Manual steps after inject @@ -20,18 +49,18 @@ Some text could be redundant or unnecessary depending on context and search for Move text around until it looks good. Remember to change any v2 usage examples. -### 3. Update `.github/workflows/main.yml` branches +### 3. Check `.github/workflows/main.yml` branches This differs from repo to repo, default is `[main]` -In a typical plugin repo with a v2 and v3 version, it will typically look like this: +In a plugin repo with a v2 and v3 version, it could look like this: ```yml # .github/workflows/main.yml name: CI & Release on: push: - branches: [main, v3] + branches: [main, studio-v2] ``` ### 4. Check secrets @@ -44,7 +73,7 @@ Ensure that your repo or Github org has set the secrets used by the workflow. Secrets can be set using `Settings -> Secrets -> Actions -> "New repository secret"` on Github for a repository. -### 5. Update .releaserc.json +### 5. Check .releaserc.json This differs from repo to repo. Branches defaults to `"branches": ["main"]` @@ -53,12 +82,13 @@ In a typical plugin repo with a v2 and v3 version, it will typically look like t ```json { "extends": "@sanity/semantic-release-preset", - "branches": ["main", {"name": "v3", "channel": "studio-v3", "prerelease": "v3-studio"}] + "branches": ["main", {"name": "studio-v2", "channel": "studio-v2", "range": "1.x.x"}] } ``` -This assumes that the v2 version lives on `main` and the v3 versions livs on `v3`. -The v3 version will be a pre-release using `studio-v3` as npm tag, and `v3-studio` version suffix. +This assumes that the v2 version lives on `studio-v2` branch and the v3 version livs on `main`. +The v2 version will be constrained to a version range and use `studio-v2` as npm tag. +The v3 version will be release with `latest` npm tag. ### 6. Test workflow and remove `--dry-run` @@ -69,6 +99,7 @@ workflow for the V3-branch and check "Release new version". Inspect the workflow logs to see the version that will be used for the release. If it is ok, remove the `--dry-run` flag from the workflow to perform a real release. + If the version is not what you expected, you might have to perform some [troubleshooting](https://semantic-release.gitbook.io/semantic-release/support/troubleshooting). @@ -82,11 +113,8 @@ Now run: This will run semantic-release in dry-run mode (no git push or npm publish) and show everything that would go into a release. -## What does it do? - -Adds opinionated config and dependencies used by the Ecosystem team on Sanity to develop using -semantic-release driven workflow on Github. +#### Note on "notable commits" +As configured, semantic-release will not consider commits starting with `docs:` or `chore:` as notable. +If you only have non-notable commits since the last release, semantic-release will not create a new version. -- Adds husky and related files and dependencies to do pre-commit checks -- Adds semantic-release and preset dependencies to automate npm & Github releases -- Updates README.md with some standard texts +Therefore, chores or doc updates that should be considered notable should use `fix(chore):` or `fix(docs):` suffix instead. diff --git a/src/presets/semver-workflow.ts b/src/presets/semver-workflow.ts index 99307c67..c5fc15e1 100644 --- a/src/presets/semver-workflow.ts +++ b/src/presets/semver-workflow.ts @@ -65,7 +65,7 @@ async function addDevDependencies(options: InjectOptions) { semantic-release preset injected. Please confer - https://github.com/sanity-io/plugin-kit/blob/main/docs/semver-workflow.md + https://github.com/sanity-io/plugin-kit/blob/main/docs/semver-workflow.md#manual-steps-after-inject to finalize configuration for this preset. `.trim() )