Merge pull request #747 from garden-io/docs-contributing

docs: update contributing docs

.chglog/config.yml

@@ -11,6 +11,7 @@ options:
         - fix
         - perf
         - refactor
+        - improvement
     sort_by: Scope
   commit_groups:
     group_by: Type

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 <hash>.`, 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 <minor | patch | preminor | prepatch | prerelease> [--force]` and does the following:
+* Checks out a branch named `release-<version>`.
+* 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 <minor | patch | preminor | prepatch | prerelease> [--force]`. The script does the following:
-    * Checks out a branch named `release-<version>`.
-    * 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 <tag-name>`.
+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 <tag-name>`.)
 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`.

commitlint.config.js

@@ -3,7 +3,6 @@ module.exports = {
   rules: {
     // Extend to add improvement key
     "type-enum": [2, "always", [
-      "build",
       "chore",
       "ci",
       "docs",

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