Skip to content

Latest commit

 

History

History
228 lines (149 loc) · 7.58 KB

CONTRIBUTING.md

File metadata and controls

228 lines (149 loc) · 7.58 KB
Raw

Contributing to SST

Want to help improve SST? Thank you! Take a second to review this document before you get started.

To be sure that you are not working on something that's already being worked on, make sure to either:

How to Contribute

In this section we'll talk about the workflow we recommend while working on SST. It's based on how we work internally, but catered specifically for our community contributors. For more context on how we work, you can check out this document.

1. Gather Requirements

When assigned an issue, the first step is to get all the details and seek any necessary clarification. If the issue was brought up by a user, make sure you fully understand the requirement from the user. Contact the user on Discord or ask them on GitHub. Or, contact a member from the core team that opened the issue.

2. Speccing

Next, do the necessary research. Draft a plan for the implementation; the cases that need to be tested; and the docs required to be updated.

Here is an example of a spec in action:

Example Task: Allow users to customize eslint rules in SST

  • Research: How is it currently done in other popular frameworks, ie. Create React App.
  • Implement: Add an eslint section in the package.json to allow users to specify a list of linting packages.
  • Implement: Update the create-sst template to prefill the package.json with SST's default linting package.
  • Test: Add a test with SST's default linting package and check the no-unused-vars rule is enforced.
  • Test: Add a test with custom linting packages and check that the no-unused-vars rule is not enforced.
  • Doc: Document the default linting package in "Working Locally" doc.
  • Doc: Show an example of customizing linting packages.

Then, add the spec to the GitHub issue. It's necessary to come up with this list before working on the task. This gives the core team a chance to propose changes. And, a good spec is one where it can be handed to anyone on the team. That person is then able to follow through and complete the implementation.

If the solution isn’t obvious or is a bigger design change, get the core team involved. Before the group discussion, come up with a proposed solution. More on this here.

The core team then reviews the spec.

3. Implement

Create a Pull Request. Inform the core team upon completion. And the core team will review the PR and merge it.

Running Locally

Here's how to run SST locally.

Clone the repo

To run this project locally, clone the repo and initialize the project.

$ git clone https://github.com/sst/sst.git
$ cd sst
$ pnpm i

SST

If you are working on SST go to the packages/sst folder and run the dev script.

$ pnpm dev

This will start a watcher that will rebuild changes you make - ensure there are no type errors before submitting a PR.

If you want to test your changes against a project you are working on you can make use of pnpm link

$ cd ./path/to/project
$ pnpm link ./path/to/sst/packages/sst/dist
$ pnpm sst dev

Note that we link to the ./dist folder since that is where we publish out of.

Docs

To run the docs site.

$ cd www
$ pnpm build
$ pnpm start

Pull Requests

Make sure to add your changes as a pull request. Start by forking the repo. Then make your changes and submit a PR.

  • Use a descriptive name for the PR
  • With the format, "[Construct/package name]: [Description]"
  • For example, "Api: Add support for HTTP proxy routes"
  • Pick a label for the PR from:
    • breaking: These are for breaking changes
    • bug: Bug fixes
    • enhancement: New features
    • documentation: Improvements to the docs or examples
    • skip changelog: Don't mention this in the release notes

If you are submitting the PR for the first time, we'll need to approve it to run the tests.

Releases

To cut a release, start by merging the PRs that are going into this release.

  1. Generate changelog

    $ pnpm changelog

    You'll need to configure the GITHUB_AUTH token locally to be able to run this. Follow these steps and configure the local environment variable.

  2. Publish a release to npm

    To publish the release to npm run:

    $ pnpm release

    Pick the version you want (patch/minor/major). This is based on the type of changes in the changelog above.

    • breaking and major enhancement changes are a minor version update
    • bug and minor enhancement changes are a patch version update

    We are not currently updating the major version until our 1.0 release.

    Verify that only the 5 core packages (core, cli, resources, create-sst, static-site-env) are getting published.

    Confirm and publish!

  3. Draft a new release

    Copy the changelog that was generated above and draft a new release.

    Make necessary edits to the changelog to make it more readable and helpful.

    • For breaking changes, add a message at the top clearly documenting the change (example).
    • For major enhancement changes, add a code snippet on how to use the feature (example).

    Add this snippet at the bottom of the changelog and replace it with the version that's going to be released.

    ---

Update using:

```sh
$ npm install --save --save-exact @sst/cli@x.x.x @sst/resources@x.x.x
```

  4. Publish GitHub release

    In the Tag version of the release draft, select the version that was just published to npm.

    Copy-paste that version as the Release title. And hit Publish release.

Canary Releases

Optionally, you can publish a canary release to npm.

This is useful if you'd like to test your release before pushing it live.

Create a canary release by running.

$ pnpm release-canary

Deprecation

Follow the checklist below when deprecating a Construct property or method.

  1. Docs: Label the old property name (or method) as deprecated.

    oldProp (deprecated)

  2. Docs: Add migration instructions under the old property (or method):

    `oldProp` has been renamed to `newProp` in v0.46.0.

If you are configuring the `oldProp` like so:

```js
new Table(this, "Table", {
  ...
  oldProp: "value",
}
```

Change it to:

```js
new Table(this, "Table", {
  ...
  newProp: "value",
}
```

  3. Construct code: Decorate the old property (or method) as deprecated.

    /**
 * @deprecated Use newProp
 */

  4. Construct code: Ensure the old property (or method) will continue to work.

  5. Construct code: Print a warning in verbose mode if the old property (or method) is used.

    WARNING: The "oldProp" property has been renamed to "newProp". "oldProp" will continue to work but will be removed at a later date. More details on the deprecation - https://docs.sst.dev/constructs/Table#secondaryindexes-deprecated

  6. Construct tests: Ensure tests added for both the old and the new property (or method).

See the Table construct for a deprecation example of renaming secondaryIndexes to globalIndexes.

Help us improve this doc. If you've had a chance to contribute to SST, feel free to edit this doc and submit a PR.