diff --git a/docs/docs/extend/publish-and-share.md b/docs/docs/extend/publish-and-share.md index 5dbd55d..85967a3 100644 --- a/docs/docs/extend/publish-and-share.md +++ b/docs/docs/extend/publish-and-share.md @@ -19,6 +19,64 @@ This guide still needs to be written. The structure below outlines what it shoul - Maintaining your package over time. ::: +## Setting Up Changeset + +Before opening a pull request with one of our repository, you should call `npm run changeset` in terminal at the root of your fork, whether of `jspsych-contrib` or `jspsych-timelines`. This will write a markdown file in `/changeset` that describes the first version of your package and any changes to it. + +We use changesets as part of our release workflow, to generate new releases to npm and their corresponding release notes. This is a [good overview of changesets](https://changesets.dev/faq#how-do-i-add-a-changeset) if you want to learn more. + +Even if you forget to include changesets before opening your pull request, jsPsych's review bot will nudge you to take care of it. You can always use the CLI and commit the changesets before merge. Note that if your package was set up with either of our `jspsych-dev` CLI tools, your package starts at version 0.0.1. + +As a shorthand, major versions (1.0.0) indicate releases that are not backwards compatible and will break users' code, while minor versions (0.1.0) indicate changes that are backwards compatible. Patches and bug fixes are indicated in the last release number (0.0.1) + +:::tip Pre-Releasing Packages +If your package isn't yet feature complete - or you plan on still making a bunch of breaking changes, like continuing to modify the API's exposed surface - we recommend pre-releasing your package and list major version as 0. +::: + +:::warning Draft Note: Set-up in developer tutorials should include forks of jspsych-contrib and jspsych-timelines +By setting that up at the start, we can set people up to return to the root of the forked repos and run changeset +::: + +## Opening a Pull Request + +Once your package directory is up to standard, you'll want to request to merge your fork - whether of `jspsych-contrib` or `jspsych-timelines` - to the original repo's `main` branch, by opening a pull request. + +### Package Contribution Checklist + +Your package is ready to merge when it includes each of the following: +- **Working package source at `src/index.js`** - or `src/index.ts` that compiles when calling `npm run build` from the command line. +- **An `examples/index.html` with working demos.** Feel free to add any number of additional HTML files to disaggregate your demos. We also recommend keeping demo assets in a separate `examples/assets/` folder or - if necessary - in an example-specific subfolder (e.g. `examples/example1/assets`). +- **A `src/index.spec.ts` with tests that all pass** when calling `npm run test` from the command line. We use Jest as the testing framework. See [testing jsPsych](contributing/dev-environment.md#testing) for more information about configuring the test tools and writing tests. +- **`README.md` introducing the package,** formatted to include an overview of what the plugin does, a `