Developing the Garden CLI framework
We heartily welcome any form of contribution to the project, including issue reports, feature requests, discussion, pull requests and any type of feedback. We request that all contributors adhere to the Contributor Covenant and work with us to make the collaboration and community productive and fun for everyone :)
Setting up your development environment
Step 1: Install Docker and Kubernetes
Please refer to our installation docs for instructions on how to install Docker and Kubernetes for different platforms.
Step 2: Clone the repo
git clone https://github.com/garden-io/garden.git
Step 3: Install dependencies
For Mac we have a script that installs all required dependencies.
If you haven't already, please install Homebrew. Then run:
Windows / Linux
Other platforms need to roll their own for now (contributions welcome!). Please have a look at the script for OSX to see what's installed.
Note: We recommend using Node 10 when developing Garden.
Step 4: Bootstrap project
Install Node modules for the root package, and the
npm run bootstrap
Before running Garden for the first time, you need to do an initial build by running
npm run build
from the root directory. This ensures that the dashboard is built and ready to serve and that version files are in place.
To develop the CLI, run the
dev command in your console:
cd garden-service npm run dev
npm link it to your global npm folder, and then watch for
changes and auto-rebuild as you code. You can then run the
garden command as normal.
Also, you might like to add a couple of shorthands:
alias g='garden' alias k='kubectl'
For developing the dashboard, please refer to the dashboard docs.
WARNING: This setup is broken on Node > 10.12 and latest versions of Chrome. See e.g. this SO post. 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:
You can e.g. use the Chrome DevTools to inspect the code at the breakpoint:
- Add a
debuggerstatement somewhere in the code.
- Navigate to chrome://inspect/ in your Chrome browser.
- Click the Open dedicated DevTools for Node link.
- Run a CLI command that hits the breakpoint, e.g.:
/path/to/garden/bin/garden-debug deploy # or gd deploy, if you've set the alias
You should now be able to inspect the code at run time in the Console tab of the DevTools window.
Tests are run using
npm test from the directory of the package you want to test. To run a specific test, you can grep the test description with the
-g flag. E.g., to the test the
taskGraph of the
cd garden-service npm test -- -g "taskGraph"
Integration tests are run with:
npm run integ
We follow the Conventional Commits 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.
We have scripts for checking licenses, docs, linting and more. These can all be run with a single command:
npm run check-all
If the checks fail because of bad formatting, run:
npm run fix-format
If the checks fail because of missing docs, run:
npm run generate-docs
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
git push origin <my-branch> --no-verify
We use Circle CI for integration testing. Sometimes
it can be useful to test and debug the CI build locally, particularly when
updating or adding dependencies. You can use their
CLI for that, which
is installed automatically by the
./bin/bootstrap-osx script. Once you
have it installed you can run
circleci build in the repo root to test
the build locally.
Every source file must include the contents of
static/license-header.txt at the top. This is
automatically checked during CI. You can run the check with
npm run check-licenses.
Our release process generates the following packages:
- An executable for OSX, Linux, and Windows, generated by Pkg and hosted on our Github page.
- A Homebrew package for OSX users.
The release script has the signature:
./bin/release.tsx <minor | patch | preminor | prepatch | prerelease> [--force] [--dry-run]
and does the following:
- Checks out a branch named
- Commits the changes, tags the commit, and pushes the tag and branch.
- Pushing the tag triggers a CI process the creates the release artifacts and publishes them to Github. If the the release is not a pre-release, we create a draft instead of actually publishing.
On every merge to
master we also publish an unstable release with the version
edge that is always flagged as a pre-release.
To make a new release, set your current working directory to the garden root directory and follow the steps below.
- The first step depends on the release type:
- If you're making the first pre-release, run
- If you’ve already created a prerelease, e.g.
v1.2.3-0, and want to create a new prerelease
v1.2.3-1which includes changes made on master since
v1.2.3-0was created, do the following:
git checkout v1.2.3-0
git rebase master
- If you’re ready to make a proper release, run
./bin/release.ts minor | patchfrom
master. This way, the version bump commits created by the prereleases are omitted from the final history.
- If you're making the first pre-release, run
- If you're making a pre-release you're done, and you can now start testing the binaries that were just published to our Github Releases tab. Otherwise go to step 3.
- Go to our Github Releases tab and click the Edit button for the draft just created from CI. Note that for drafts, a new one is always created instead of replacing a previous one.
- Write release notes. 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
- Click the Publish release button.
- Make a pull request for the branch that was pushed by the script.
- Update the Homebrew package:
We keep a changelog under
CHANGELOG.md that get's updated on every release. For pre-releases, we include every pre-release tag in that release cycle in the changelog. So if we're releasing, say,
v0.9.1-3, the changelog will include entries for
v0.9.1-2, assuming those tags exist. Once we make a proper release, we remove the pre-release tags so that the changelog only shows changes between
v0.9.1. A changelog with the pre-releases is of course always available in our Git history.