Build a Release

The following page describes exactly from the perspective of a developer what has to be done to get a new release that (as a last step) can be published to the public without missing anything. It will / was be used the first time for the release 1.6.7.

Overall procedures

1. Define what will be in the scope of the next release, and decide if it is

• a patch release: only small changes / bug fixes, no new feature completed, no change in API.
• a minor release: new feature, change in API, but backward compatible. It has to be safe to do an upgrade, and expect your usage to be valid again.
• a major release: breaking changes / new features that are not backward compatible; expectation that people that have done a deep integration have to adapt that as well.

2. Ensure that the following files are updated:

• package.json: the new release number
• docs/docu|examples|index.html: the new release number
• Changelog.md: Go through all commits since the last release, and look for issue links

3. Depending on the changes, check if new examples should be provided

• for new features: find the right location for at least one example
• for bug fixes: in the sub-directory tickets, follow the convention with name ticket<NNN>.html.

4. Build a new library locally: npm run build and run a server in the examples directory: npm run server examples.
5. Go through all files in the examples directory, and see if they work as expected. Try to use at least the critical examples, and the ones that may be touched by the changes.
6. Link the current version globally, and ensure that examples/react is working with the new version.
7. Build the documentation again: npm run gen_examples, copy the library to the directory docs/lib.
8. Run the documentation: npm run server docs, and check the documentation.
9. If anything was changed during your checking, please start again from beginning, to avoid late errors.
10. Do a build again at the end, ensure that the files in lib are copied to docs/lib.
11. Commit and push on the main branch, and double check if the release is built, and does not fail on the server.
12. Publish the new release on NPM: npm publish --access public.
13. After publishing, check on npm that the new release is available: https://www.npmjs.com/package/@mliebelt/pgn-viewer

Linking / unlinking

To test if a new version will work integrated in an another package, you have to link / unlink it then.

1. Go the root directory, and call npm link.
2. Go to the directory examples/react/test-pgn-viewer-app, and call npm link "@mliebelt/pgn-viewer" to link the local version.
3. Test your changes, and ensure that the react application is starting.
4. After testing, take it back the in directory examples/react/test-pgn-viewer-app by calling npm unlink "@mliebelt/pgn-viewer".
5. Then in the root directory with npm unlink.

Updating documentation

Include information what may be updated, and how to see and do it then.

Updating examples

A first draft, when and why examples are built, and how they can be improved (over time)

Publishing to NPM

What are the necessary things I have to understand, how can things be tested, when critical changes are done, before doing the publication (to not burn some versions), ...