From 6511fb094ef34c5b5395b5afa2432af809b10428 Mon Sep 17 00:00:00 2001
From: Michael van der Kamp <michael.vanderkamp@usask.ca>
Date: Tue, 18 Aug 2026 20:47:50 -0700
Subject: [PATCH] Add contribution guide with release process

---
 CHANGELOG.md    |   2 +-
 CONTRIBUTING.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |   7 +++-
 3 files changed, 115 insertions(+), 2 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1245931..fec4918 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,6 @@
 # Changelog
 
-## 1.3.1
+## Unreleased
 
 - Add 'contextmenu' to CANCEL_EVENTS
 - Changed docs deployment strategy
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..5956246
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,108 @@
+# Contributing to westures-core
+
+Thanks for contributing to westures-core. Contributions to the gesture engine,
+tests, documentation, and examples are welcome.
+
+## Development Setup
+
+This project uses npm and is [tested in CI](./.github/workflows/node.js.yml) across a matrix of recent Node versions.
+
+Install dependencies with:
+
+```sh
+npm clean-install --ignore-scripts
+```
+
+## Common commands
+
+Run the same checks used by CI before opening a pull request:
+
+```bash
+npm run build
+npm run lint
+npm test
+npm run test:coverage
+```
+
+Additional useful commands:
+
+```bash
+npm run build:debug
+npm run lint:fix
+```
+
+## Development Workflow
+
+- Keep changes focused and update tests when behavior changes.
+- Update `CHANGELOG.md` for notable user-facing, maintenance, or security changes.
+- Open a pull request using the repository's pull request template.
+
+The source is in `src/`, tests are in `test/`, and `index.js` is the package
+entry point. The `dist/` directory contains build output; regenerate it with
+`npm run build` rather than editing it directly.
+
+Follow the existing JavaScript style. ESLint enforces the project conventions,
+including two-space indentation, single quotes, semicolons, and trailing commas
+in multiline constructs.
+
+## Pull Requests
+
+Before opening a pull request, run the build, linter, and relevant tests. Give
+the pull request a clear description, explain any behavioral changes, and use
+the provided pull request template to identify its type. Keep unrelated
+formatting or refactoring changes out of the pull request.
+
+For bugs, include a regression test when practical. For user-facing API or
+behavior changes, update the README and JSDoc documentation as appropriate.
+
+## Reporting Issues
+
+When reporting a bug, include the Node.js version, browser and version when
+relevant, a minimal reproduction, expected behavior, and actual behavior.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+[MIT License](LICENSE).
+
+## Release process
+
+For a package release, use the following workflow so you publish from the same
+source commit you tag (with build artifacts generated locally), while only
+pushing the tag after `npm publish` succeeds.
+
+1. Create a release preparation branch from `main`.
+2. Update `package.json`, `package-lock.json`, and `CHANGELOG.md` for the new version.
+3. Commit the release preparation changes and open a pull request.
+4. Merge the pull request into `main`.
+5. Check out the merged `main` commit locally.
+6. Verify the working tree is clean.
+7. Create the release tag locally for that commit, but do not push it yet.
+8. Check what will be published with `npm pack --dry-run`.
+9. Sanity-check the built bundle in `dist/index.js`.
+10. Publish the package to npm from the tagged commit.
+11. Push the tag.
+12. Create the GitHub release from the pushed tag.
+
+Example commands for `1.3.1`:
+
+```bash
+git switch --create release/1.3.1
+git add package.json package-lock.json CHANGELOG.md
+git commit --message "Prepare for 1.3.1 release"
+gh pr create
+# merge the PR, then sync your local main to the merged commit
+git switch main
+git pull --ff-only origin main
+git status --short  # must produce no output
+git tag --annotate v1.3.1 --message "Release 1.3.1"
+npm pack --dry-run  # also builds, via 'prepare' script
+ls -lh dist/index.js
+npm publish
+git push origin v1.3.1
+gh release create v1.3.1 --title "v1.3.1"
+```
+
+If you want GitHub release notes to match the changelog closely, paste the
+`1.3.1` section of `CHANGELOG.md` into the release notes when creating the
+release.
diff --git a/README.md b/README.md
index c0b4060..04adf33 100644
--- a/README.md
+++ b/README.md
@@ -67,6 +67,7 @@ region.addGesture(follow);
 - [Nomenclature and Origins](#nomenclature-and-origins)
 - [Changes](#changes)
 - [Issues](#issues)
+- [Contributing](#contributing)
 - [Links](#links)
 
 ## Features
@@ -303,6 +304,11 @@ most recent updates.
 
 If you find any issues, please let me know!
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and pull
+request guidelines.
+
 ## Links
 
 ### westures
@@ -316,4 +322,3 @@ If you find any issues, please let me know!
 - [npm](https://www.npmjs.com/package/westures-core)
 - [github](https://github.com/mvanderkamp/westures-core)
 - [documentation](https://mvanderkamp.github.io/westures-core/)
-