Skip to content

Commit

Permalink
Update docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
milesj committed Sep 20, 2023
1 parent 73bb392 commit eaa505d
Showing 10 changed files with 72 additions and 49 deletions.
12 changes: 7 additions & 5 deletions packages/cli/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Changelog

## Unreleased
## Future roadmap

#### 🚀 Updates

@@ -9,12 +9,14 @@
- Better concurrency handling and scheduling.
- More accurately monitors signals (ctrl+c) and shutdowns.
- Tasks can now be configured with a timeout.
- Updated `moon ci` to support running a list of targets, instead of running everything.

#### 🐞 Fixes
## Unreleased

#### 🚀 Updates

- Updated `version` settings to be parsed as semantic version objects instead of strings. This
should be transparent to users, but listing it just in case.
- Updated `moon ci` to support running an explicit list of targets, instead of running everything.
- Updated `node.version`, `npm.version`, `pnpm.version`, `yarn.version`, and `rust.version` to
support partial versions and requirements/ranges like `1.2`, `1`, or `^1.2`.

#### ⚙️ Internal

35 changes: 32 additions & 3 deletions website/docs/concepts/toolchain.mdx
Original file line number Diff line number Diff line change
@@ -16,16 +16,45 @@ necessary tools, _and_ to keep them in sync as time passes.

## How it works

The toolchain is built around [proto](/proto), our stand-alone toolchain manager. moon will
piggyback of proto's toolchain found at `~/.proto` and reuse any tools available, or download and
install them if they're missing.
The toolchain is built around [proto](/proto), our stand-alone multi-language version manager. moon
will piggyback of proto's toolchain found at `~/.proto` and reuse any tools available, or download
and install them if they're missing.

## Configuration

The tools that are managed by the toolchain are configured through the
[`.moon/toolchain.yml`](../config/toolchain) file, but can be overridden in each project with
[`moon.yml`](../config/project#toolchain).

### Version specification

As mentioned above, tools within the toolchain are managed _by version_ for consistency across
machines. These versions are configured on a per-tool basis in
[`.moon/toolchain.yml`](../config/toolchain). So what kinds of versions are allowed?

- **Full versions** - A full version is a semantic version that is fully specified, such as `1.2.3`
or `2.0.0-rc.1`. This is the most common way to specify a version, and is preferred to avoid
subtle deviations.
- **Partial versions** - A partial version is a version that is either missing a patch number, minor
number, or both, such as `1.2` or `1`. These can also be represented with requirement syntax, such
as `^1.2` or `~1`. If using partials, we suggest having a major and minor number to reduce the
deviation of versions across machines.
- **Aliases** - An alias is a human-readable word that maps to a specific version. For example,
`latest` or `stable` maps to the latest version of a tool, or `canary` which maps to applicable
canary release, or even a completely custom alias like `berry`. Aliases are language specific, are
not managed by moon, and are not suggested for use since they can change at any time (or even
daily!).

This sounds great, but how exactly does this work? For full versions and aliases, it's straight
forward, as the resolved version is used as-is (assuming it's a legitimate version), and can be
found at `~/.proto/tools/<tool>/<version>`.

For partial versions, we first check locally installed versions for a match, by scanning
`~/.proto/tools/<tool>`. For example, if the requested version is `1.2` and we have `1.2.10`
installed locally, we'll use that version instead of downloading the latest `1.2.*` version.
Otherwise, we'll download the latest version that matches the partial version, and install it
locally.

## Supported tools

The following tools are currently managed by the toolchain.
7 changes: 5 additions & 2 deletions website/docs/config/project.mdx
Original file line number Diff line number Diff line change
@@ -962,7 +962,8 @@ Currently, only the Node.js version can be overridden per-project, not the packa

#### `version`

Defines the explicit Node.js version to use when _running tasks_ for this project.
Defines the explicit Node.js [version specification](../concepts/toolchain#version-specification) to
use when _running tasks_ for this project.

```yaml title="moon.yml" {2,3}
toolchain:
@@ -978,7 +979,9 @@ Configures Rust for this project and overrides the top-level [`rust`](./toolchai

#### `version`

Defines the explicit Rust version/channel to use when _running tasks_ for this project.
Defines the explicit Rust
[version/channel specification](../concepts/toolchain#version-specification) to use when _running
tasks_ for this project.

```yaml title="moon.yml" {2,3}
toolchain:
33 changes: 14 additions & 19 deletions website/docs/config/toolchain.mdx
Original file line number Diff line number Diff line change
@@ -103,19 +103,16 @@ Enables and configures [Node.js](../guides/javascript/node-handbook).

<HeadingApiLink to="/api/types/interface/NodeConfig#version" />

Defines the explicit Node.js version to use. We require an explicit and semantic major, minor, and
patch version, to ensure the same environment is used across every machine. Ranges are _not_
supported.

If this field is _not defined_, the global `node` binary will be used.
Defines the explicit Node.js [version specification](../concepts/toolchain#version-specification) to
use. If this field is _not defined_, the global `node` binary will be used.

```yaml title=".moon/toolchain.yml" {2}
node:
version: '16.13.0'
version: '16.13'
```

> Version can also be defined with [`.prototools`](../proto/config) or be overridden with the
> `MOON_NODE_VERSION` environment variable.
> Version can also be defined with [`.prototools`](../proto/config) or with the `MOON_NODE_VERSION`
> environment variable.

### `packageManager`

@@ -140,10 +137,9 @@ latest version of the active package manager will be used (when applicable).

<HeadingApiLink to="/api/types/interface/NodePackageManagerConfig#version" />

The `version` setting defines the explicit package manager version to use. We require an explicit
major, minor, and patch version, to ensure the same environment is used across every machine.

If this field is _not defined_, the global `npm`, `pnpm`, and `yarn` binaries will be used.
The `version` setting defines the explicit package manager
[version specification](../concepts/toolchain#version-specification) to use. If this field is _not
defined_, the global `npm`, `pnpm`, and `yarn` binaries will be used.

```yaml title=".moon/toolchain.yml" {4}
node:
@@ -152,8 +148,8 @@ node:
version: '3.1.0'
```

> Version can also be defined with [`.prototools`](../proto/config) or be overridden with the
> `MOON_NPM_VERSION`, `MOON_PNPM_VERSION`, or `MOON_YARN_VERSION` environment variables.
> Version can also be defined with [`.prototools`](../proto/config) or with the `MOON_NPM_VERSION`,
> `MOON_PNPM_VERSION`, or `MOON_YARN_VERSION` environment variables.

### `yarn`

@@ -516,14 +512,13 @@ Enables and configures [Rust](../guides/rust/handbook).

<HeadingApiLink to="/api/types/interface/RustConfig#version" />

Defines the explicit Rust toolchain version/channel to use. We require an explicit and semantic
major, minor, and patch version, to ensure the same environment is used across every machine.

If this field is _not defined_, the global `cargo`, `rustc`, and other binaries will be used.
Defines the explicit Rust toolchain
[version/channel specification](../concepts/toolchain#version-specification) to use. If this field
is _not defined_, the global `cargo`, `rustc`, and other binaries will be used.

```yaml title=".moon/toolchain.yml" {2}
rust:
version: '1.69.0'
version: '1.69'
```

> Version can also be defined with [`.prototools`](../proto/config).
6 changes: 3 additions & 3 deletions website/docs/config/workspace.mdx
Original file line number Diff line number Diff line change
@@ -540,9 +540,9 @@ projects, this may be fine, but for larger projects, this may be undesirable and

<HeadingApiLink to="/api/types/interface/WorkspaceConfig#versionConstraint" />

Defines a semantic version requirement for the currently running moon binary. This provides a
mechanism for enforcing that the globally installed moon on every developers machine is using an
applicable version.
Defines a version requirement for the currently running moon binary. This provides a mechanism for
enforcing that the globally installed moon on every developers machine is using an applicable
version.

```yaml title=".moon/workspace.yml" {1}
versionConstraint: '>=0.20.0'
10 changes: 1 addition & 9 deletions website/docs/create-project.mdx
Original file line number Diff line number Diff line change
@@ -71,15 +71,7 @@ following:
```yaml title="apps/client/moon.yml"
tasks:
build:
command:
- 'webpack'
- 'build'
- '--mode'
- 'production'
- '--entry'
- 'src/index.tsx'
- '--output-path'
- 'build'
command: 'webpack build --mode production --entry src/index.tsx --output-path build'
inputs:
- 'src/**/*'
outputs:
2 changes: 1 addition & 1 deletion website/docs/intro.mdx
Original file line number Diff line number Diff line change
@@ -158,5 +158,5 @@ This service is currently in heavy development.

## proto

[proto](/proto) is a toolchain manager for your favorite programming languages.
[proto](/proto) is a version manager for your favorite programming languages.
[View proto documentation](/docs/proto).
8 changes: 5 additions & 3 deletions website/docs/setup-toolchain.mdx
Original file line number Diff line number Diff line change
@@ -62,8 +62,9 @@ node:
version: '18.0.0'
```

This setting requires a fully qualified semantic version and _does not_ support version ranges, so
be sure to use an explicit version. We suggest _always_ using an
This setting can be a fully qualified semantic version (preferred), a partial version (missing patch
or minor), or even an alias (learn more about the
[version specification](./concepts/toolchain#version-specification)). We suggest _always_ using an
[Active LTS](https://nodejs.org/en/about/releases/) version.

Let's now run [`moon setup --log debug`](./commands/setup) to verify that Node.js is downloaded and
@@ -91,7 +92,8 @@ node:
```

By default moon will install a stable version of the package manager, but this isn't consistently
updated, so we suggest defining an explicit semantic version for the package manager as well,
updated, so we suggest defining a
[version specification](./concepts/toolchain#version-specification) for the package manager as well,
through the [`node.<packageManager>.version`](./config/toolchain#version-1) setting.

```yaml title=".moon/toolchain.yml"
4 changes: 2 additions & 2 deletions website/src/pages/index.tsx
Original file line number Diff line number Diff line change
@@ -132,8 +132,8 @@ export default function Home() {
<Link href="/moon" size="lg">
proto
</Link>
, our modern toolchain manager, this entire workflow is automated away through a
single tool.
, our modern version manager, this entire workflow is automated away through a single
tool.
</>
}
cta={{
4 changes: 2 additions & 2 deletions website/src/pages/proto.tsx
Original file line number Diff line number Diff line change
@@ -50,8 +50,8 @@ const toolchainFeatures: Feature[] = [
export default function ProductProto() {
return (
<Layout
title="proto - A multi-language toolchain manager"
description="Lightspeed toolchain manager for programming languages and their dependency managers."
title="proto - A multi-language version manager"
description="Lightspeed version manager for programming languages and their dependency managers."
>
<Hero />

0 comments on commit eaa505d

Please sign in to comment.