Skip to content

Commit

Permalink
Deploy to GitHub Pages
Browse files Browse the repository at this point in the history
  • Loading branch information
skuba committed Aug 15, 2023
0 parents commit efe3773
Show file tree
Hide file tree
Showing 39 changed files with 8,409 additions and 0 deletions.
2,392 changes: 2,392 additions & 0 deletions CHANGELOG.md

Large diffs are not rendered by default.

257 changes: 257 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,257 @@
---
nav_order: 99
---

# Contributing

---

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.

---

## Getting started

**skuba** is documented through its [README](README.md),
along with some targeted topics under the [docs](docs) directory.
We maintain a [changelog] and [release notes] on GitHub,
and distribute it as an [npm package].

### 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, start a discussion in [#typescriptification].

### 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.

If you work at SEEK, start a discussion in [#skuba-development].

---

## Development

### Prerequisites

**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 16+
- Yarn 1.x

Next, install npm dependencies:

```shell
yarn install
```

### Git workflow

We use [GitHub flow](https://guides.github.com/introduction/flow/).

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

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

Develop, [test](#testing) and commit your changes on this branch.
(Make sure to include the appropriate [changeset](#creating-a-changeset).)

```shell
git add --all
git commit
```

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

```shell
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:

```shell
git remote add fork [email protected]: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.

### Testing

You may find it easier to develop alongside unit tests:

```shell
export NODE_OPTIONS=--experimental-vm-modules

yarn test --watch
```

Format your code once you're happy with it:

```shell
yarn format
```

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

```shell
yarn lint
yarn test
```

Our [validate](https://github.com/seek-oss/skuba/blob/master/.github/workflows/validate.yml) 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.

```shell
# greeter | koa-rest-api | ...
yarn test:template greeter

# clean up temporary sibling directory
rm -fr ../tmp-greeter
```

### Running locally

If you want to try out the **skuba** CLI on itself,
a `yarn skuba` script is configured:

```shell
# 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,
use [yarn link]:

```shell
# Do this once upfront.
yarn link

# `yarn link` points to the JavaScript output in `./lib`.
# This means you'll need to rebuild skuba on every code change 😔.
yarn build

# Link your local skuba binary to another local repo.
cd ../some-other-repo
yarn link skuba

# Run skuba commands against the other repo.
yarn skuba version

# Avoid command confusion after you're done.
cd -
yarn unlink
```

---

## 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 **skuba** interface,
which includes:

- [API](https://github.com/seek-oss/skuba/tree/master/src/api) for Node.js build and test code
- [CLI](https://github.com/seek-oss/skuba/tree/master/src/cli) commands
- [Config](https://github.com/seek-oss/skuba/tree/master/config) presets
- [Template](https://github.com/seek-oss/skuba/tree/master/template) code and documentation
- [npm dependencies](https://github.com/seek-oss/skuba/blob/master/package.json)

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

- Documentation like the [README](README.md)
- Internal refactoring that preserves the existing interface
- [npm dev dependencies](https://github.com/seek-oss/skuba/blob/master/package.json)

```shell
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.

```text
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](https://github.com/seek-oss/skuba/tree/master/.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 [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](https://github.com/seek-oss/skuba/blob/master/.github/workflows/release.yml) GitHub Actions workflow will publish the associated GitHub release and npm package version.

### Publishing a prerelease

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.

<https://www.npmjs.com/package/skuba?activeTab=versions>

[#skuba-development]: https://slack.com/app_redirect?channel=C03UM9GBGET
[#typescriptification]: https://slack.com/app_redirect?channel=CDCPCEPV3
[changelog]: CHANGELOG.md
[changesets]: https://github.com/atlassian/changesets
[create a pull request]: https://github.com/seek-oss/skuba/compare
[fork the repo]: https://github.com/seek-oss/skuba/fork
[npm package]: https://www.npmjs.com/package/skuba
[release notes]: https://github.com/seek-oss/skuba/releases
[seek-oss/changesets-snapshot]: https://github.com/seek-oss/changesets-snapshot
[semantic versioning]: https://semver.org/
[snapshot workflow]: https://github.com/seek-oss/skuba/actions/workflows/snapshot.yml
[submit an issue]: https://github.com/seek-oss/skuba/issues/new/choose
[windows subsystem for linux]: https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux
[yarn link]: https://classic.yarnpkg.com/lang/en/docs/cli/link/
19 changes: 19 additions & 0 deletions _config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
include:
- CHANGELOG.md
- CONTRIBUTING.md
title: skuba

remote_theme: pmarsceill/just-the-docs

aux_links:
GitHub:
- https://github.com/seek-oss/skuba
npm:
- https://www.npmjs.com/package/skuba
aux_links_new_tab: true

gh_edit_link: true
gh_edit_link_text: Edit this page
gh_edit_repository: https://github.com/seek-oss/skuba
gh_edit_branch: master
gh_edit_view_mode: tree
80 changes: 80 additions & 0 deletions docs/about.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
---
nav_order: 97
---

# About

---

## Goals

### Speed up prototyping and project creation

### Standardise tooling

**skuba** tracks technology recommendations from [SEEK's Technology Strategy].

### Reduce maintenance overhead

**skuba** bundles developer tooling into one `package.json#/devDependency`.

This tooling is managed and upgraded for you.
Upgrades are consolidated into one Renovate PR.

---

## Non-goals

### Support for vanilla JavaScript

TypeScript is proposed as the default language of SEEK.

**skuba** prescribes TypeScript-focused tooling.

### One stencil to rule them all

**skuba** may advocate for certain approaches and technologies through its templates,
but this shouldn't be taken as the only way you can write code.

You can continue to base codebases on your own starters and stencils.

### One library to rule them all

**skuba** distributes a minimal runtime component through the **skuba-dive** package.
It has no aspirations of becoming a monolithic Node.js runtime library.

SEEK's developer community maintains an assortment of targeted packages.

Here are some highlights:

| Package | Description |
| :----------------------------- | :----------------------------------------------------- |
| [@seek/logger] | Write application logs in a standardised format |
| [seek-datadog-custom-metrics] | Write Datadog metrics in [Gantry] and Lambda |
| [seek-koala] | Add SEEK-standard observability to Koa servers |
| 🔒 [@seek/db-client] | Connect to databases with credential (rotation) smarts |
| 🔒 [@seek/graphql-utils] | Add observability to GraphQL servers |
| 🔒 [@seek/node-s2sauth-issuer] | Call an [s2sauth]-protected service |
| 🔒 [@seek/typegen] | Generate TypeScript types from a JSON schema |
| 🔒 [@seek/zactive-directory] | Authenticate and authorise [SSOd] users |

---

## Related reading

- [SEEK's Technology Strategy]
- SEEK's frontend development toolkit, [sku]

[@seek/db-client]: https://github.com/SEEK-Jobs/db-client
[@seek/graphql-utils]: https://github.com/SEEK-Jobs/graphql-utils
[@seek/logger]: https://github.com/seek-oss/logger
[@seek/node-s2sauth-issuer]: https://github.com/SEEK-Jobs/node-s2sauth-issuer
[@seek/typegen]: https://github.com/SEEK-Jobs/typegen
[@seek/zactive-directory]: https://github.com/SEEK-Jobs/zactive-directory
[gantry]: https://backstage.myseek.xyz/docs/default/component/gantry/
[s2sauth]: https://github.com/SEEK-Jobs/s2sauth
[seek-datadog-custom-metrics]: https://github.com/seek-oss/datadog-custom-metrics
[seek-koala]: https://github.com/seek-oss/koala
[seek's technology strategy]: https://tech-strategy.ssod.skinfra.xyz
[sku]: https://github.com/seek-oss/sku
[ssod]: https://github.com/SEEK-Jobs/seek-ssod-ingress
Loading

0 comments on commit efe3773

Please sign in to comment.