generator-custom-template

News Design Monorepo

This monorepo contains multiple packages that help create and publish custom stories for the News Design and Graphics departments. They can all be found in the /packages directory.

• bespoke-tool Bootstrap an Apple News story inside a custom template project
• create-custom-template Create a custom template project with one command
• custom-template The Next.js template created by the create-custom-template package
• custom-template-utils Utility functions to share across custom template packages and projects
• pub-tool A CLI tool for publishing custom-template projects

Documentation

There are a few sources of documentation, other than this README:

• Confluence for workflow documentation
• Storybook for component documentation, written in the /stories directory. You can see these locally by running npm run storybook.
• Each package also has its own README: bespoke-tool, create-custom-template, custom-template, custom-template-utils, pub-tool.

Getting started

Read more on how to best contribute to this project in our contributing guide.

If you run into issues, a more comprehensive getting started guide is in the Custom Template Onboarding guide.

Node and npm versions

The codebase runs on Node version 20.11.0 and npm 10.2.4. We manage the version of Node and npm with nvm.

1. Install nvm with these instructions.
2. Once installed, run nvm use. You may be prompted to install the version of Node. The output should be "Now using node v20.11.0 (npm 10.2.4)".
3. If npm is not on version 10.2.4, you can update it with: npm i -g npm@10.2.4 and then check the version with npm --version.
4. Run npm install from the repo's root. This will install all dependencies for all of our monorepo packages at once, and properly symlink them.

Configuration file

You'll need to create a configuration file in your home directory. Follow these steps to create one.

Ensure you have a pub profile for WP-MAIN set up in Clokta

This template fetches and saves environment variables via AWS Systems Manager Parameter Store. Follow these instruction to set up your pub or newseng profile. When running npm install you will be asked at the end to confirm your AWS access to download .env files.

Release process

Releases are staged and tested in an automated "Next Release" PR that collects all changes to dev. Release are made by following the steps below. Merging the "Next Release" PR will kick off a Lerna workflow that creates a Github tag, Github release, changelogs for each package, and publishing packages to npm. Reach out in the #template-custom if you need a release and we can walk through the process.

1. Run through the pre-release test steps. (You can skip this step if you feel the release won't affect creating or publishing a project.)
2. Allow merge commits and uncheck all branch protections on main
3. Ensure all test have passed on the Next Release PR. You will likely need to approve the Chromatic's UI Tests at the bottom of the PR. To do this click "Details" to the right of "UI Tests", log in with Github, and approve the changes. If there is an unexpected change, share the change in custom-template-devs.
4. ‼️Create a merge commit‼️ (Do not squash and merge!) the "Next Release" PR into main. Name the commit "ci: Next Release" (This is the same as the description). This kicks off a Lerna scripts that will: Determine the next version number based on conventional commits, write the release notes, and create a Github tag and version.
5. Head to the Github Actions status page and wait for the release action to complete. You should see a green checkmark when it has finished successfully.
6. Click here to create a PR to sync main back into dev and ‼️create a merge commit‼️ back to dev. Call the PR chore: Sync dev with main
7. Disallow merge commits and re-instate the following branch protections on main:
   • Require a pull request before merging
     • Require approvals
     • Dismiss stale pull request approvals when new commits are pushed
   • Require status checks to pass before merging
     • Require branches to be up to date before merging
8. Run through the post-release test steps. (You can skip this step if you feel the release won't affect creating or publishing a project.)
9. Write a note in #template-custom after the release is out and, if the release note is long, add that note to the releases documentation in Confluence.

Pre-release test

Before we do a full release, we want to ensure someone can create, run, and publish a story from the dev branch. Run though the following steps:

1. Update the slug on the test article in Ellipsis. This will allow you to make another test pub from the same ID.
2. Check out the dev branch locally and run npm install to ensure you have all the latest packages.
3. Run npm run create-test-project
4. Use this utils ellipsis ID when prompted: JNG2MGCOENBY3K4GJFWF3U3C6Q.
5. Once it’s done installing, cd into the new project’s directory and run npm start to make sure you can start a project with no errors.
6. Run npm run pub and make a test pub.
7. Run npm run pub and make a live pub. The utils ellipsis ID above prevents the page from being publicly accessible. Check to make sure the live pub has /utils in the URL. If not, reach out for help in the #custom-template Slack channel.
8. After you've tested both those links, delete the test repo that you just created.

Post-release test

After we do a release, we want to ensure the same process works from the npm package. Run though the following steps that are similar to the pre-release steps:

1. Update the slug on the test article in Ellipsis. This will allow you to make another test pub from the same ID.
2. Run npx @washingtonpost/create-custom-template@latest.
3. Use this utils ellipsis ID: JNG2MGCOENBY3K4GJFWF3U3C6Q.
4. Once it’s done installing, cd into the new project’s directory and check that the package.json version matches the recent release version number.
5. Inside your project directory, run npm start to make sure the project starts with no errors.
6. Run npm run pub and make a test pub.
7. Run npm run pub and make a live pub. The utils ellipsis ID above prevents the page from being publicly accessible. Check to make sure the live pub has /utils in the URL. If not, reach out for help.
8. After you've tested both those links, delete the test repo that you just created.

Release a beta

1. Sync with dev and create a new branch off of dev. Name it "beta-release-[MMDD]"
2. Run npm run lerna-publish:beta
3. Confirm correct beta version. It should ask you if you want to increment one number higher than what is on npmjs.org. You can check this by going to the packages here: pub-tool, create-custom-template, utils, bespoke-tool, utils.
4. Once the beta-release succeeds, PR your branch. Merge promptly with dev.

Amending a release

A version should not be updated after a release! If there was an issue with a release, release another new version.

Lerna looks at the conventional commits to determine what what features and fixes to place in the change log. Sometimes commits make it in with the wrong package, type, or typos. You can amend those note by updating the CHANGELOG.md and updating the release notes in Github.

Cherry-pick a release

Sometimes we need to do a release to get one feature or fix out quickly without merging all changes from dev with the "Next Release" PR. To do this, follow these steps:

1. Create a new branch called "next-release" from main and check it out locally.
2. On your local branch, run git cherry-pick with the commit hash you want to release.
3. Make a PR that points to main and ensure all tests pass.
4. Remove branch protections on main. Read the release process to learn how.
5. Once the tests pass, merge your release PR into main.
6. Once the release is done, merge main back into dev to sync the new versions and changes.
7. Re-instate branch protections.
8. Write a note in #custom-template after the release is out.

Hotfixing a previous major release

If we've introduced an important fix to a newer version of a package, we can selectively grab an older version and apply the fix for older projects:

1. Check the tag history for the latest previous production release of the package you want to apply a patch to. For example, if pub-tool's latest version is 2.X, you would grab the commit ID for the latest 1.X version that wasn't a beta or alpha.
2. Run git checkout [Commit ID]
3. Create a new branch from this commit by running git checkout -b hotfix-[package name]
4. cd into the package you are needing to make a fix to. i.e. cd generator-custom-template/packages/pub-tool
5. Make the needed fix or adjustment.
6. Bump the specific package's version number up by a minor in package.json. For example, increment the pub-tool package.json version from 1.7.2 to 1.7.3.
7. Commit and push up the branch (You can delete the branch later but its good to keep around until you're sure it's no longer needed).
8. From the package directory (Not the root of the monorepo!), run npm publish.

Troubleshooting

Bumping all those dependabot packages

Dependabot will diligently and somewhat ruthlessly remind us about what packages are behind. You can merge in each PR at a time on github, but that can be risky if it's a major bump or maybe breaks something in our build. The best way is to make a new PR with all the open PRs and test them together locally.

1. Make a new branch and call it something like bump-dependencies
2. Go though the dependabot PRs and update the all package.json to the new versions.
3. After you made the bumps, run nvm use to make sure you are using the right version of node and npm (this will affect the package lock version).
4. Run npm i in the root to make sure the new dependencies install correctly and you get a new package-lock.json. We use npm's workspaces under the hood which knows how to communicate with all of our monorepo packages and will properly update/symlink as needed. There should only be one package-lock.json file and it will be in the root.
5. Now test the packages with the usual scripts:

• npm run start
• npm t
• npm run build-storybook
• cd packages/create-custom-template/template and run npm run prod-preview
• npm run pub and make a test pub can be a nice check too if the pub tool was updated

Keep in mind the script on test 8 will run throughout the development and release process, but it's easier to catch dependencies errors now than later.

Fragments in Storybook

The <Story> component doesn’t like siblings as first descendants. Avoid that by wrapping them in Fragment/<> or divs.

Pulling stories

To download a dropbox paper or google sheet, you can run npm run download in the template directory.

For Ellipsis stories, your story is automatically re-downloaded every time you hit save on a file inside the src folder in your project.

A fun alternative to all of the above: You can create a bookmark tab in your browser that will download any type of story you have listed. To do so, create the bookmark first, then set its link to: javascript:(fetch(window.location.href + 'update').then(f=>console.log('updated stories')))