From 58c75447be3a9dbc11ac4b310c4099d428d2153b Mon Sep 17 00:00:00 2001 From: vminojosa Date: Tue, 18 Aug 2026 14:32:40 -0400 Subject: [PATCH 1/3] first pass at publish-and-share with description of how best to open a pull request; includes some information from contributing.md that will be worked into the package contribution list; only thing missing completely for now is inclusion in browse.md --- docs/docs/extend/publish-and-share.md | 41 +++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/docs/extend/publish-and-share.md b/docs/docs/extend/publish-and-share.md index 5dbd55d..7e222bc 100644 --- a/docs/docs/extend/publish-and-share.md +++ b/docs/docs/extend/publish-and-share.md @@ -19,6 +19,47 @@ 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 use `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. + +:::warning Draft Note: patch version shorthand +include the patch version shorthand here from the demo for hackathon +::: + +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 give you a nudge anyway. You can always use the CLI and commit the changesets before merge. + +:::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 + +### Package Contribution Checklist + +When your package is ready to merge, it should include each of the following: +- a `src/index.js` (or `src/index.ts`) that compiles when `npm run build` is run from the command line +- a `examples/index.html` with working demos + - An example file should be included if applicable. If you are contributing a new feature, new plugin, or new extension, or contributing a modification that changes the behavior of the library in some important way, consider adding an example file to the /examples folder in the repository. +- a `src/index.spec.ts` with tests that all pass when `` is run from the command line + - The code must be tested through our automated testing system. We use Jest as the testing framework. If you are fixing a bug, consider adding a test case that shows the bug has been resolved. If you are contributing new features, like a new plugin, a test suite for the plugin is very helpful. See testing jsPsych for more information about configuring the test tools and writing tests. +- `README.md` formatted to include overview, parameters summary, and examples +- Docs parsed from `src` and rendered at `docs/plugin-name.md` + - Relevant documentation must be updated. Any pages in /docs that are affected by the contribution should be updated, and if new pages are needed they should be created. For example, if you are contributing a plugin then adding documentation for the plugin and updating the list of available plugins as well as the mkdocs configuration file is very helpful! +- Citation metadata + - If you are contributing a plugin/extension, we strongly encourage including a file containing citation information. This file should be named CITATION.cff and placed at the root of your repository. This allows people who use your plugin/extension in their code to easily cite your work by calling `jsPsych.getCitations([])` from their command line. More information on .cff files can be found here. +- Changesets for major release 1.0.0 + +### Pull Request Format + +Your open pull request should include the following in the first comment: +- **An overview** describing what the plugin does and its default behavior +- **A feature list** +- **A breakdown of files included in the PR.** This should mirror and confirm what should be accounted for in the package checklist. +- **An author line** listing who worked on the package. + ## See also - [Build a plugin](plugins/plugin-tutorial.md) From b963b5a93160f494789c785b9b6b48001f3e4684 Mon Sep 17 00:00:00 2001 From: vminojosa Date: Mon, 24 Aug 2026 13:49:04 -0400 Subject: [PATCH 2/3] rewrote the relevant portions of the old contributing.md language to fit the context of the checklist, finished a first draft of a pull request form section, finished the setting up changeset section with and admonition for pre-releasing, and included a section at the end for non-package contributions --- docs/docs/extend/publish-and-share.md | 54 +++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/docs/docs/extend/publish-and-share.md b/docs/docs/extend/publish-and-share.md index 5dbd55d..f6930b7 100644 --- a/docs/docs/extend/publish-and-share.md +++ b/docs/docs/extend/publish-and-share.md @@ -19,6 +19,60 @@ 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 use `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 give you a nudge anyway. You can always use the CLI and commit the changesets before merge. + +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 `