From 15cf7f7c97c812998e69669dc875cadee277d775 Mon Sep 17 00:00:00 2001 From: james0209 Date: Mon, 29 Apr 2024 22:48:13 +0100 Subject: [PATCH] Lint Markdown --- README.md | 82 +++++++++++++++++++++++--------------------- docs/CONTRIBUTING.md | 10 +++--- 2 files changed, 47 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 9e8b640..0d55191 100644 --- a/README.md +++ b/README.md @@ -14,55 +14,55 @@ the library in ad-hoc or CI shell scripting outside of Go. `hc-install` does **not**: - - Determine suitable installation path based on target system. e.g. in `/usr/bin` or `/usr/local/bin` on Unix based system. - - Deal with execution of installed binaries (via service files or otherwise). - - Upgrade existing binaries on your system. - - Add nor link downloaded binaries to your `$PATH`. +- Determine suitable installation path based on target system. e.g. in `/usr/bin` or `/usr/local/bin` on Unix based system. +- Deal with execution of installed binaries (via service files or otherwise). +- Upgrade existing binaries on your system. +- Add nor link downloaded binaries to your `$PATH`. ## API The `Installer` offers a few high-level methods: - - `Ensure(context.Context, []src.Source)` to find, install, or build a product version - - `Install(context.Context, []src.Installable)` to install a product version +- `Ensure(context.Context, []src.Source)` to find, install, or build a product version +- `Install(context.Context, []src.Installable)` to install a product version ### Sources The `Installer` methods accept number of different `Source` types. Each comes with different trade-offs described below. - - `fs.{AnyVersion,ExactVersion,Version}` - Finds a binary in `$PATH` (or additional paths) - - **Pros:** - - This is most convenient when you already have the product installed on your system +- `fs.{AnyVersion,ExactVersion,Version}` - Finds a binary in `$PATH` (or additional paths) + - **Pros:** + - This is most convenient when you already have the product installed on your system which you already manage. - - **Cons:** - - Only relies on a single version, expects _you_ to manage the installation - - _Not recommended_ for any environment where product installation is not controlled or managed by you (e.g. default GitHub Actions image managed by GitHub) - - `releases.{LatestVersion,ExactVersion}` - Downloads, verifies & installs any known product from `releases.hashicorp.com` - - **Pros:** - - Fast and reliable way of obtaining any pre-built version of any product - - Allows installation of enterprise versions - - **Cons:** - - Installation may consume some bandwidth, disk space and a little time - - Potentially less stable builds (see `checkpoint` below) - - `checkpoint.LatestVersion` - Downloads, verifies & installs any known product available in HashiCorp Checkpoint - - **Pros:** - - Checkpoint typically contains only product versions considered stable - - **Cons:** - - Installation may consume some bandwidth, disk space and a little time - - Currently doesn't allow installation of old versions or enterprise versions (see `releases` above) - - `build.GitRevision` - Clones raw source code and builds the product from it - - **Pros:** - - Useful for catching bugs and incompatibilities as early as possible (prior to product release). - - **Cons:** - - Building from scratch can consume significant amount of time & resources (CPU, memory, bandwith, disk space) - - There are no guarantees that build instructions will always be up-to-date - - There's increased likelihood of build containing bugs prior to release - - Any CI builds relying on this are likely to be fragile + - **Cons:** + - Only relies on a single version, expects _you_ to manage the installation + - _Not recommended_ for any environment where product installation is not controlled or managed by you (e.g. default GitHub Actions image managed by GitHub) +- `releases.{LatestVersion,ExactVersion}` - Downloads, verifies & installs any known product from `releases.hashicorp.com` + - **Pros:** + - Fast and reliable way of obtaining any pre-built version of any product + - Allows installation of enterprise versions + - **Cons:** + - Installation may consume some bandwidth, disk space and a little time + - Potentially less stable builds (see `checkpoint` below) +- `checkpoint.LatestVersion` - Downloads, verifies & installs any known product available in HashiCorp Checkpoint + - **Pros:** + - Checkpoint typically contains only product versions considered stable + - **Cons:** + - Installation may consume some bandwidth, disk space and a little time + - Currently doesn't allow installation of old versions or enterprise versions (see `releases` above) +- `build.GitRevision` - Clones raw source code and builds the product from it + - **Pros:** + - Useful for catching bugs and incompatibilities as early as possible (prior to product release). + - **Cons:** + - Building from scratch can consume significant amount of time & resources (CPU, memory, bandwidth, disk space) + - There are no guarantees that build instructions will always be up-to-date + - There's increased likelihood of build containing bugs prior to release + - Any CI builds relying on this are likely to be fragile ## Example Usage -See examples at https://pkg.go.dev/github.com/hashicorp/hc-install#example-Installer. +See examples at . ## CLI @@ -70,9 +70,9 @@ In addition to the Go library, which is the intended primary use case of `hc-ins The CLI comes with some trade-offs: - - more limited interface compared to the flexible Go API (installs specific versions of products via `releases.ExactVersion`) - - minimal environment pre-requisites (no need to compile Go code) - - see ["hc-install is not a package manager"](https://github.com/hashicorp/hc-install#hc-install-is-not-a-package-manager) +- more limited interface compared to the flexible Go API (installs specific versions of products via `releases.ExactVersion`) +- minimal environment pre-requisites (no need to compile Go code) +- see ["hc-install is not a package manager"](https://github.com/hashicorp/hc-install#hc-install-is-not-a-package-manager) ### Installation @@ -82,7 +82,7 @@ Given that one of the key roles of the CLI/library is integrity checking, you sh [Homebrew](https://brew.sh) -``` +```sh brew install hashicorp/tap/hc-install ``` @@ -102,7 +102,7 @@ You can follow the instructions in the [Official Packaging Guide](https://www.ha ### Usage -``` +```text Usage: hc-install install [options] -version This command installs a HashiCorp product. @@ -113,10 +113,12 @@ Usage: hc-install install [options] -version -log-file Path to file where logs will be written. /dev/stdout or /dev/stderr can be used to log to STDOUT/STDERR. ``` + ```sh hc-install install -version 1.3.7 terraform ``` -``` + +```sh hc-install: will install terraform@1.3.7 installed terraform@1.3.7 to /current/working/dir/terraform ``` diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 23ce140..b406406 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -6,8 +6,8 @@ Releases are made on a reasonably regular basis by the maintainers (HashiCorp st Release process: - 1. Update [`version/VERSION`](https://github.com/hashicorp/hc-install/blob/main/version/VERSION) to remove `-dev` suffix and set it to the intended version to be released - 1. Wait for [`build` workflow](https://github.com/hashicorp/hc-install/actions/workflows/build.yml) to finish - 1. Run the Release workflow with the appropriate version (matching the one in `version/VERSION`) & SHA (long one). - 1. Wait for a message in the Slack channel saying that authorisation is needed to promote artifacts to production. Click on the link and approve. - 1. Once notified that promotion is successful, go to https://github.com/hashicorp/crt-workflows-common/actions/workflows/promote-production-packaging.yml, locate the hc-install promote-production-packaging workflow, and approve. +1. Update [`version/VERSION`](https://github.com/hashicorp/hc-install/blob/main/version/VERSION) to remove `-dev` suffix and set it to the intended version to be released +1. Wait for [`build` workflow](https://github.com/hashicorp/hc-install/actions/workflows/build.yml) to finish +1. Run the Release workflow with the appropriate version (matching the one in `version/VERSION`) & SHA (long one). +1. Wait for a message in the Slack channel saying that authorisation is needed to promote artifacts to production. Click on the link and approve. +1. Once notified that promotion is successful, go to , locate the hc-install promote-production-packaging workflow, and approve.