diff --git a/docs/publishing.md b/docs/publishing.md index fc00e224b8..5cae60384b 100644 --- a/docs/publishing.md +++ b/docs/publishing.md @@ -12,16 +12,55 @@ version bumped. ### Publishing components manually (while in Alpha/Private beta) -In a new branch that is up to date with the master branch: - -1. Update `CHANGELOG` with the new version number and the changes made. - -2. Run the `npm run build:packages` task. This copies any changes from -`src/components/component-name` to `packages/component-name`. -Note: The command also runs tests to ensure the contents of `packages` match `src`. -These tests live in `after-build-packages.test.js`. - -3. In Frontend, for any new components inside `/packages`, add a `package.json` +*First time only: Shell scripts will require permission to run. +Run `chmod u+x **/*.sh` which will give the permission to all shell +scripts in the current directory.* + +**If you have a new component to add, follow [these](#adding-a-new-component) steps** + +1. Create a new branch that's up to date with master and: + +2. Update `CHANGELOG` version heading with the next version number. + +3. Run `npm run prerelease` task. + This will: + - run `npm build:packages` that copies any changes from`src/component-name` to `packages/component-name` and runs `after-build-packages.test.js` test + to ensure the contents of `packages` matches `src`. + - run `lerna publish --skip-git --skip-npm` which will check for updated packages and + suggest a version for each as seen below. + Lerna will prompt you to select the new version for each package. If you + select `minor`/`major` etc., Lerna will complete the version number for you. In + private beta, we have selected `custom` and specified the new version number + manually for each package (see below). Also see step 3 regarding the versioning + of new components: + ![Select version in Lerna](./img/lerna-select-version.png) + Once you confirm changes, all files are automatically added and commited with + the commit message `Release ` and pushed to origin. + ![Confirm publishing of changes in Lerna](./img/lerna-confirm-publish.png) + + - run `npm build:dist` that copies any changes from`src/component-name` to `dist/components/component-name` and runs `after-build-dist.test.js` test + to ensure the contents of `dist/componenents` matches `src`. + It compiles and minifies CSS and JavaScript and applies version number + (taken from `all/package.json` file), e.g `govuk-frontend--alpha.min`. + Finally it copies all icons from the `src/icons`. + +4. Create a pull request for these changes. When reviewing the PR check version of compile assets and check release notes for the changes made. + +5. Once the pull request is approved, merge to **master** and run `npm run release` in **master**. + This will: + - check if you're logged in to NPM as the correct user. If not, it will abort. + - run `npm publish` for each package if the package hasn't been published yet + (the currect version matches the version on NPM) + - `git tag v` if current git tag doesn't match latest published tag + - push the tag to remote with `git push --tags` + - create a zip file of the `dist` directory with + `git archive -o ./release-.zip HEAD:dist` + +6. Create a release in Github interface, ddd release notes to and attach the ZIP. + +#### Adding a new component + +1. In Frontend, for any new components inside `/packages`, add a `package.json` inside `packages/component-name`: ``` { @@ -32,94 +71,22 @@ inside `packages/component-name`: } } ``` - - Here, the version number must be completed for new components (leaving it - blank throws an error when running `lerna bootstrap`). Use the new version - number of component. (Lerna will ask you to enter the new version number again - as part of `lerna publish` in step 11 so you'll effectively be "updating" - to the same version number - this part of the publishing process needs - some work.) - - Include any dependencies, such as the `icons` package, that the new component - requires. Use the current version number of any packages that you include here, - Lerna will update the version number if necessary as part of `lerna publish`. - -4. Include new components in `packages/all/package.json` with blank version + +2. Include new components in `packages/all/package.json` with blank version numbers. Do not update the version numbers of existing packages manually here, Lerna will do this as part of `lerna publish`. -5. Commit changes made so far +3. Commit changes made so far ``` git add packages/* -f -git commit -m "chore(packages): copy changes to packages" +git commit -m "chore(packages): added to packages" ``` +#### Test published packages -6. At this point, run `git status` to make sure no changes have been introduced -since the commit in the previous step. (Any contents of the `packages` folder -will get pushed to npm in step 11.) - -7. In the console, log in to npm as user who has permission to publish to the -`govuk-frontend` scope. You can use `npm whoami` to check your current user. - -8. Run -``` -lerna bootstrap -``` -You should see `lerna success Bootstrapped [number of] packages`. This will -install all package dependencies and link any cross-dependencies. - -9. Run -``` -lerna updated -``` -This will display the packages that have changed. - -10. Run -``` -lerna publish -m "chore(release): update packages and publish" -``` -Here, Lerna will prompt you to select the new version for each package. If you -select `minor`/`major` etc., Lerna will complete the version number for you. In -private beta, we have selected `custom` and specified the new version number -manually for each package (see below). Also see step 3 regarding the versioning -of new components: -![Select version in Lerna](./img/lerna-select-version.png) - -11. Once you have updated all the package versions, confirm you want to publish -the changes (see below). -![Confirm publishing of changes in Lerna](./img/lerna-confirm-publish.png) - -12. If your changes included new packages, you need to grant npm test user -access to them: -``` -npm access grant read-only govuk-frontend:test @govuk-frontend/warning-text -``` -Note: If you rename a package as part of the release, npm will consider it to be -a new package. You will need to grant test user access to the new package. - -13. OPTIONAL: Login at `https://www.npmjs/login` as the test user to check which -packages the user has now access to. - -14. To test the packages have published correctly, in console login as the test +1. To test the packages have published correctly, in console login as the test user. In the Design System, run `npm install` and then `npm start`. Check that the changes have taken effect. -15. Update `dist` folder with the latest versions -``` -npm run build:dist -``` -``` -git add dist/* -git commit -m "chore(dist): update dist to version x.x.x-alpha" -git push --tags -``` -Note: Specifying `--tags` here will push the release tags to origin. -Note: The command also runs tests to ensure the contents of `dist` match `src`. -These tests live in `after-build-dist.test.js`. - -16. Open a PR for these changes. - -17. Run `lerna clean` to remove `node_modules` directory created in each package. -As documented in [Lerna docs](https://github.com/lerna/lerna/#clean) - ## Updating other repos that consume `govuk-frontend` If you need to update `govuk-frontend` to the latest release on another repo