Hi there, thanks for checking out our repo!
Scoobie is a component library for SEEK documentation sites.
While third-party contributions are certainly welcome, this library has minimal value if you aren't committed to our design system and development toolkit.
SEEKers: this repo is public, so don't commit or post anything that isn't ready for the entire world to see.
Scoobie is documented through its README and Storybook site. We maintain release notes on GitHub, and distribute it as an npm package.
Submit an issue if you have a question, feature request or bug report.
If you work at SEEK, #indirect is your friend.
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.
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
- Yarn 1.x
Next, install npm dependencies:
yarn installWe use GitHub flow.
Create a new branch off of the latest commit on master:
git fetch origin
git switch --create your-branch-name origin/masterDevelop, test and commit your changes on this branch. (Make sure to use a semantic commit message.)
git add --all
git commitFinally, push your branch to GitHub and create a pull request:
git push --set-upstream origin your-branch-nameIf 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/scoobie.git
git push --set-upstream fork your-branch-nameA maintainer will get to your pull request and review the changes. If all is well, they will merge your pull request into master.
Start a local Storybook server to preview your changes:
yarn storybook:startWhile the Storybook server is running, you can run visual regression tests with Loki:
yarn loki:testIf you meant to make visual changes, you can update the Loki snapshots:
yarn loki:updateFormat your code once you're happy with it:
yarn formatWe run linting and testing in CI, but consider running these commands locally for a faster feedback loop:
yarn lint
yarn testWe 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 Scoobie interface, which includes:
- Top-level exports from src/index.ts
- Top-level exports from webpack/index.js
- Bundled configuration files types.d.ts and typography.ts
- npm dependencies
On the other hand, a changeset is not necessary for:
- Documentation like the README
- Internal refactoring that preserves the existing interface
- npm dev dependencies
yarn changesetThe 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.
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 changelog.
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.
Prereleases can be created on demand via seek-oss/changesets-snapshot.
Run the Snapshot workflow in GitHub Actions to publish a new snapshot version to npm.