Hi there, thanks for checking out our repo!
skuba is a toolkit for developing TypeScript backend applications and packages at SEEK. While third-party contributions are certainly welcome, this project is primarily driven by our internal priorities and technology strategy.
SEEKers: this repo is public, so don't commit or post anything that isn't ready for the entire world to see.
skuba is documented through its README, along with some targeted topics under the docs directory. We maintain a changelog and 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, #typescriptification 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.
skuba is predominantly tested on macOS and Linux. If you're on Windows, we recommend the Windows Subsystem for Linux.
First, some JavaScript tooling:
- Node.js 14+
- Yarn 1.x
Next, install npm dependencies:
yarn install
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/skuba.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.
You may find it easier to develop alongside unit tests:
yarn test --watch
Format your code once you're happy with it:
yarn format
We run linting and testing in CI, but consider running these commands locally for a faster feedback loop:
yarn lint
yarn test
Our validate GitHub Actions workflow also initialises each built-in skuba template and runs through a set of CLI commands. This can be reproduced locally, but keep in mind that the script is fairly slow and you'll have to manually clean up afterwards.
# greeter | koa-rest-api | ...
yarn test:template greeter
# clean up temporary sibling directory
rm -fr ../tmp-greeter
If you want to try out the skuba CLI on itself,
a yarn skuba
script is configured:
# prints available commands
yarn skuba
# prints version from local package.json
yarn skuba version
# builds skuba using itself
yarn skuba build
If you want to try out the skuba CLI on another local repo, you can use npm link to register your local copy as a global shell command:
# do this once upfront
npm link
# npm link points to the compiled JavaScript in ./lib/index.js, so
# you'll need to rebuild skuba on every code change
yarn build
# run a skuba command against another repo
cd ../some-other-repo
skuba version
# avoid command confusion after you're done
npm unlink
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 skuba interface, which includes:
- API for Node.js build and test code
- CLI commands
- Config presets
- Template code and documentation
- 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 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
Prefix your changeset title with a **scope:**
.
This makes it easy to eyeball which part of skuba a change relates to.
**test:** Fix command
**template:** Add next steps to READMEs
**template/koa-rest-api:** Switch to Express
**format, lint:** Introduce new ESLint rule
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.
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
yarn changeset pre enter beta
yarn changeset version
If previous betas have been released under the same semantic version, you will need to manually bump the version suffix in package.json:
- "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