diff --git a/.chglog/config.yml b/.chglog/config.yml index acc0c3350b..f4d1e1bd59 100755 --- a/.chglog/config.yml +++ b/.chglog/config.yml @@ -11,6 +11,7 @@ options: - fix - perf - refactor + - improvement sort_by: Scope commit_groups: group_by: Type diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f4f37043af..fcb89dc4b6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,25 +7,6 @@ discussion, pull requests and any type of feedback. We request that all contribu adhere to the [Contributor Covenant](CODE_OF_CONDUCT.md) and work with us to make the collaboration and community productive and fun for everyone :) -## Commit messages - -We follow and automatically validate -[Angular-like formatting](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits) for our -commit messages, for consistency and clarity. In particular, the **type** of the commit header must be one of the following: - -* **feat**: A new feature -* **fix**: A bug fix -* **docs**: Documentation only changes -* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing - semi-colons, etc) -* **refactor**: A code change that neither fixes a bug nor adds a feature -* **perf**: A code change that improves performance -* **test**: Adding missing or correcting existing tests -* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation - generation - -When generating the changelog, we only include the following types: **feat**, **fix**, **refactor**, and **perf**. This means that any changes that the user should be aware of, should have one of these types. - ## Setting up your development environment ### Step 1: Install Docker and Kubernetes @@ -91,6 +72,8 @@ For developing the dashboard, please refer to the [dashboard docs](./dashboard/R ### Debugging +**WARNING: This setup is broken on Node > 10.12 and latest versions of Chrome. See e.g. this [SO post](https://stackoverflow.com/questions/48994836/chrome-devtools-dedicated-node-js-inspector-not-stopping-at-breakpoints). The solutions suggested there have not worked.** + To enable setting a breakpoint in the code, run the CLI with the `garden-service/bin/static/garden-debug` binary, which adds the `--inspect` flag. Developers might find it useful to alias this: ```sh @@ -126,6 +109,26 @@ Integration tests are run with: npm run integ ``` +### Commit messages + +We follow the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0-beta.4/#specification) and automatically validate the formatting of our commit messages. In particular, the **type** of the commit header must be one of the following: + +* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation + generation. +* **ci**: Changes to the CI configuration. +* **docs**: Documentation only changes. +* **feat**: A new feature. +* **fix**: A bug fix. +* **improvement**: Changes that improve a current implementation without adding a new feature or fixing a bug. +* **perf**: A code change that improves performance. +* **refactor**: A code change that neither fixes a bug nor adds a feature. +* **revert**: A commit that reverts a previous commit. It should begin with `revert: `, followed by the header of the reverted commit. In the body it should say: `This reverts commit .`, where the hash is the SHA of the commit being reverted. +* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing + semi-colons, etc). +* **test**: Adding missing or correcting existing tests. + +When generating the changelog, we only include the following types: **feat**, **fix**, **refactor**, **improvement**, and **perf**. This means that any changes that the user should be aware of, should have one of these types. + ### Checks We have scripts for checking licenses, docs, linting and more. These can all be run with a single command: @@ -134,6 +137,18 @@ We have scripts for checking licenses, docs, linting and more. These can all be npm run check-all ``` +If the checks fail because of bad formatting, run: + +```sh +npm run fix-format +``` + +If the checks fail because of missing docs, run: + +```sh +npm run generate-docs +``` + ### Pre-push hook Before pushing, we automatically run the `check-all` script from above, as well as unit and integration tests. To skip these, run push with the `--no-verify` flag: @@ -159,22 +174,38 @@ automatically checked during CI. You can run the check with `npm run check-licen ## Release process +### Packages + Our release process generates the following packages: * An executable for OSX, Linux, and Windows, generated by [Pkg](https://github.com/zeit/pkg) and hosted on our [Github page](https://github.com/garden-io/garden/releases). * A [Homebrew](https://brew.sh/) package for OSX users. +### Process + +The release process is twofold, first a [release script](https://github.com/garden-io/garden/blob/master/bin/release.ts) is run. The script has the signature: `./bin/release.tsx [--force]` and does the following: +* Checks out a branch named `release-`. +* Updates `package.json` and `package-lock.json` for `garden-service` and the changelog. +* Commits the changes, tags the commit and pushes the tag and branch, triggering a CI process the creates the release artifacts. + +Second, we manually upload the artifacts generated in CI to our Github releases page and then write the release notes. + +### Steps + To make a new release, set your current working directory to the garden root directory and follow the steps below. -1. Run the release script: `./bin/release.tsx [--force]`. The script does the following: - * Checks out a branch named `release-`. - * Updates `package.json` and `package-lock.json` for `garden-service` and the changelog. - * Commits the changes, tags the commit and pushes the tag and branch, triggering a CI process the creates the release artifacts. +1. The first step depends on the release type: + * If you're making the first pre-release, run `./bin/release.tsx prerelease` from `master`. + * If you’ve already created a prerelease, e.g. `v1.2.3-0`, and want to create a new prerelease `v1.2.3-1` which includes changes made on master since `v1.2.3-0` was created, do the following: + * `git checkout v1.2.3-0` + * `git rebase master` + * `./bin/release.ts prerelease` + * If you’re ready to make a proper release, run `./bin/release.ts minor | patch` from `master`. This way, the version bump commits created by the prereleases are omitted from the final history. 2. Open the [Garden project on CircleCI](https://circleci.com/gh/garden-io/garden) and browse to the job marked `release-service-pkg`. Open the **Artifacts** tab and download the listed artifacts. 3. Go to our Github [Releases tab](https://github.com/garden-io/garden/releases) and click the **Draft a new release** button. 4. Fill in the **Tag version** and **Release title** fields with the new release version (same as you used for the tag). 5. Upload the downloaded artifacts. -6. Write release notes (not necessary for RCs). The notes should _at least_ contain the changelog. To generate a changelog for just that tag, run `git-chglog `. +6. Write release notes (not necessary for RCs). The notes should give an overview of the release and mention all relevant features. They should also **acknowledge all external contributors** and contain the changelog for that release. (To generate a changelog for just that tag, run `git-chglog `.) 7. Click the **Publish release** button. 8. Make a pull request for the branch that was pushed by the script. 9. If you're making an RC, you're done! Otherwise, you need to update Homebrew package: `gulp update-brew`. diff --git a/commitlint.config.js b/commitlint.config.js index 24e3c77429..0e87d55cc6 100644 --- a/commitlint.config.js +++ b/commitlint.config.js @@ -3,7 +3,6 @@ module.exports = { rules: { // Extend to add improvement key "type-enum": [2, "always", [ - "build", "chore", "ci", "docs", diff --git a/dashboard/README.md b/dashboard/README.md index 6fe4980a5a..64f10f3763 100644 --- a/dashboard/README.md +++ b/dashboard/README.md @@ -1,22 +1,22 @@ # Garden Dashboard _(experimental)_ -This directory contains an experimental web dashboard for the Garden CLI. The dashboard is available on `localhost` when either the `garden dev` or `garden serve` commands are running. +This directory contains an experimental web dashboard for the Garden CLI. The dashboard is available on `localhost` when Garden is running in watch mode, e.g. `garden dev` or `garden build -w`, or when the `garden serve` command is run. All commands below assume that the current directory is root. ## Usage -To use with the Garden CLI, simply run: +To use with the Garden CLI, simply run a Garden command in watch mode inside some Garden project. E.g: ```sh -cd garden-service +cd examples/simple-project garden serve ``` or alternatively ```sh -cd garden-service +cd examples/simple-project garden dev ``` @@ -27,8 +27,8 @@ and follow the dashboard link printed by the command. To develop the dashboard, first run: ```sh -cd garden-service -garden serve # (or garden dev) +cd examples/simple-project # (or some other Garden project) +garden serve # (or some watch mode command) ``` to start the `garden-service` API server. Then run: @@ -67,11 +67,15 @@ REACT_APP_GARDEN_SERVICE_PORT=my_port npm start See also `src/setupProxy.js` and [Adding Custom Environment Variables](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables). +## Linking `garden-cli` + +To be able to import type definitions from the `garden-cli` package, we first link it to the `dashboard` package with the `npm link` command. This step happens automatically when running `npm run dev`. + ## Build To build the dashboard, run: -``` +```sh cd dashboard npm run build ```