Skip to content

Latest commit

 

History

History
228 lines (162 loc) · 6.54 KB

CONTRIBUTING.md

File metadata and controls

228 lines (162 loc) · 6.54 KB
Raw

Contributing

Hi there, thanks for checking out our repo!

Wingman serves as a practical reference for third-party developers integrating with the SEEK API, and complements the detailed documentation on our developer site. While third-party contributions are certainly welcome, this project is primarily driven by our internal priorities.

SEEKers: this repo is public, so don't commit or post anything that isn't ready for the entire world to see.

Table of contents

Getting started

Wingman is documented through its README. We maintain changelogs and release notes on GitHub, and distribute underlying components as npm packages (wingman-fe).

Frontend components can be previewed through a Storybook. We plan to host the Wingman example stack publicly at some point (#3).

See the README design section for more details on the repository structure.

I want to discuss or report something

Submit an issue if you have a question, feature request or bug report.

If you work at SEEK, #indirect is your friend.

I want to contribute a change

Feel free to create a pull request for trivial fixes and improvements.

For more substantial features, please submit an issue first. This lets us evaluate whether the feature fits the direction of the project and discuss possible approaches.

Development

Prerequisites

We depend on upstream tooling like sku that are predominantly tested on macOS and Linux. If you're on Windows, we recommend the Windows Subsystem for Linux.

First, some JavaScript tooling:

  • Node.js LTS
  • pnpm as per package.json#packageManager

Next, install npm dependencies:

pnpm install

Git workflow

We use GitHub flow.

Create a new branch off of the latest commit on master:

git fetch origin
git switch --create your-branch-name origin/master

Develop, test and commit your changes on this branch. (Make sure to include the appropriate changeset.)

git add --all
git commit

Finally, push your branch to GitHub and create a pull request:

git push --set-upstream origin your-branch-name

If you don't have push access, you may need to fork the repo and push there instead:

git remote add fork git@github.com:your-username/wingman.git
git push --set-upstream fork your-branch-name

A maintainer will get to your pull request and review the changes. If all is well, they will merge your pull request into master.

Testing

You may find it easier to develop alongside unit tests:

pnpm fe test --watch

Format your code once you're happy with it:

pnpm format

We run linting and testing in CI, but consider running these commands locally for a faster feedback loop:

pnpm lint
pnpm test

Running locally

Start local development servers:

pnpm fe start

Releases

Creating a changeset

We use Changesets to manage package releases. You'll see a 🦋 bot gliding around pull requests.

You should write a changeset if you are changing the public Wingman interface, which includes:

  • Package code under fe/lib
  • npm dependencies

On the other hand, a changeset is not necessary for:

  • Documentation like the README
  • Example code under fe/example
  • Internal refactoring that preserves the existing interface
  • npm dev dependencies
pnpm changeset

The Changesets CLI is interactive and follows semantic versioning:

  • Patch release 0.0.X: fixes or tweaks to existing functionality
  • Minor release 0.X.0: new, backwards-compatible functionality
  • Major release X.0.0: backwards-incompatible modification

The Changesets CLI will generate a Markdown file under .changeset, which you should include in your pull request. It doesn't need to be part of the same commit as the rest of your changes. Feel free to manually edit this file to include more details about your change.

Publishing a release

When a pull request with a changeset is merged, our CI workflow will create a new Version Packages PR. The changesets are used to infer the next semantic version and to update the changelogs.

This PR may be left open to collate multiple changes into the next version. A maintainer will merge it once ready, and our release GitHub Actions workflow will publish the associated GitHub release and npm package version.

Publishing a prerelease

We currently have limited support for prereleases on the beta dist-tag. This can only be performed by a maintainer.

# revert beta branch to match master
git fetch origin
git switch beta
git reset --hard origin/master

# stage a beta release
pnpm changeset pre enter beta
pnpm changeset version

If previous betas have been released under the same semantic version, you will need to manually bump the version suffixes in the package.json(s):

- "version": "4.0.0-beta.1",
+ "version": "4.0.0-beta.2",

Then, commit and push your changes:

git add --all
git commit --message 'Publish v4.0.0-beta.2'
git push --set-upstream origin beta