Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: document versioning #377

Merged
merged 4 commits into from
Sep 23, 2022
Merged

docs: document versioning #377

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
40a2219
wip
blaugold Sep 12, 2022
b338e62
docs: document versioning
blaugold Sep 16, 2022
811b6a6
fixup
blaugold Sep 16, 2022
e8b5e92
Update docs/guides/automated-releases.mdx
Salakar Sep 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 66 additions & 34 deletions docs/configuration/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,15 @@ all the configurable fields and their purpose.

> required

The name of this project, using for display purposes within IO environments and IDEs.
The name of this project for display purposes within IO environments and IDEs.

```yaml
name: My Awesome Project
```

## `repository`

The URL of where the git repository, which contains this project, is centrally hosted.
The URL of the git repository that contains the Melos workspace.

Supported hosts:

Expand All @@ -33,13 +33,16 @@ repository: https://github.com/invertase/melos

## `sdkPath`

> optional

Path to the Dart/Flutter SDK that should be used.

Relative paths are resolved relative to the `melos.yaml` file.

To use the system-wide SDK, provide the special value "auto".

If the SDK path is specified though multiple mechanisms, the precedence from highest to lowest is:
If the SDK path is specified though multiple mechanisms, the precedence from
highest to lowest is:

1. `--sdk-path` global command line option
2. `MELOS_SDK_PATH` environment variable
Expand All @@ -53,8 +56,8 @@ sdkPath: .fvm/flutter_sdk

> required

A list of paths to local packages that are included in the Melos workspace. Each entry can be
specific path or a [glob] pattern.
A list of paths to local packages that are included in the Melos workspace. Each
entry can be a specific path or a [glob] pattern.

```yaml
packages:
Expand All @@ -66,70 +69,85 @@ packages:
- .
```

> You can also reduce the scope of packages on a per-command basis via the [`--scope` filter](/filters#scope) flag.
> You can also reduce the scope of packages on a per-command basis via the
> [`--scope` filter](/filters#scope) flag.

## `ignore`

A list of paths to local packages that are excluded from the Melos workspace. Each entry can be
specific path or a [glob] pattern.
> optional

A list of paths to local packages that are excluded from the Melos workspace.
Each entry can be a specific path or a [glob] pattern.

```yaml
ignore:
# e.g. ignore example apps
- "packages/**/example"
- 'packages/**/example'
```

> You can also expand the scope of ignored packages on a per-command basis via the [`--scope` filter](/filters#scope) flag.
> You can also expand the scope of ignored packages on a per-command basis via
> the [`--scope` filter](/filters#scope) flag.

## `ide`

> optional

Configuration for realting to IDE support.

## `ide/intellij/enabled`

Whether to generate IntelliJ IDEA config files to improve the developer experience when working
in a Melos workspace.
Whether to generate IntelliJ IDEA config files to improve the developer
experience when working in a Melos workspace.

The default is `true`.

```yaml
ide:
intellij:
enabled: false # set to false to override default and disable
enabled: false # set to false to override default and disable
```

## `ide/intellij/moduleNamePrefix`

Used when generating IntelliJ project modules files, this value specifies a string to prepend to a package's IntelliJ
module name. Use this to avoid name collisions with other IntelliJ modules you may already have in place.
Used when generating IntelliJ project modules files. This value specifies a
string to prepend to a package's IntelliJ module name. Use this to avoid name
collisions with other IntelliJ modules you may already have in place.

The default is 'melos_'.
The default is 'melos\_'.

## `scripts`

> optional

Define custom scripts that can be executed in the workspace via the [`melos run`](/commands/run) command.
Define custom scripts that can be executed in the workspace via the
[`melos run`](/commands/run) command.

Learn more about defining scripts [here](/configuration/scripts).

## `command`

> optional

Configuration relating to specific Melos commands such as versioning.

### `command/bootstrap`

Configuration for the `bootstrap` command.

### `command/bootstrap/usePubspecOverrides`

Whether to use `pubspec_overrides.yaml` for overriding workspace dependencies during development.
Whether to use `pubspec_overrides.yaml` for overriding workspace dependencies
during development.

Enabling this option requires Dart **2.17.0** or greater.

When this option is enabled, Melos will generate a `pubspec_overrides.yaml` file in the root of
every package during bootstrapping. This file should not be tracked in version control and should
be added to `.gitignore`.
When this option is enabled, Melos will generate a `pubspec_overrides.yaml` file
in the root of every package during bootstrapping. This file should not be
tracked in version control and should be added to `.gitignore`.

This mechanism has the advantage that it does not conflict with other tooling such as the `dart`
and `flutter` tools and IDE plugins, compared to the original mechanism used to link local packages.

A caveat is that because of a bug in `pub`, whose fix is not yet in the stable channel, publishing
of packages cannot be performed while `pubspec_overrides.yaml` exists. A workaround is to run
`melos clean` before `melos publish`, which removes `pubspec_overrides.yaml`s if they were
generated by Melos.
This mechanism has the advantage that it does not conflict with other tooling
such as the `dart` and `flutter` tools and IDE plugins, when compared to the
original mechanism used to link local packages.

### `command/bootstrap/runPubGetInParallel`

Expand All @@ -145,13 +163,18 @@ Useful in closed network environments with pre-populated pubcaches.

The default is `false`.

### `command/version`

Configuration for the `version` command.

### `command/version/message`

A template for the commit message, that is generated by `melos version`.

Templates must use mustache syntax and have the following variables available:

- `new_package_versions`: A list of the versioned packages and their new versions.
- `new_package_versions`: A list of the versioned packages and their new
versions.

The default is:

Expand All @@ -172,7 +195,8 @@ command:

### `command/version/branch`

If specified, prevents `melos version` from being used inside branches other than the one specified.
If specified, prevents `melos version` from being used inside branches other
than the one specified.

```yaml
command:
Expand All @@ -192,7 +216,8 @@ command:

### `command/version/includeCommitId`

Whether to add short commit id (no links) in the CHANGELOG.md, that is generated by `melos version`.
Whether to add short commit ids to commits (no links) in the CHANGELOG.md that
is generated by `melos version`.

```yaml
command:
Expand All @@ -202,7 +227,8 @@ command:

### `command/version/linkToCommits`

Whether to add links to commits in the CHANGELOG.md, that is generated by `melos version`.
Whether to add links to commits in the CHANGELOG.md that is generated by
`melos version`.

Enabling this option, requires [`repository`](#repository) to be specified.

Expand All @@ -214,7 +240,8 @@ command:

### `command/version/workspaceChangelog`

Whether to additionally build a CHANGELOG.md at the root of the workspace when running `melos version`.
Whether to additionally build a CHANGELOG.md at the root of the workspace when
running `melos version`.

```yaml
command:
Expand All @@ -224,7 +251,12 @@ command:

### `command/version/updateGitTagRefs`

When running `melos version` this option will allow updates to `pubspec.yaml` for locally (git) hosted packages part of this melos workspace, see [here](/guides/automated-releases#git-hosted-packages)
Whether to update package version tags in git dependencies of dependents when
versioning packages.

See the
[automated releases documentation](/guides/automated-releases#git-hosted-packages)
for more information.

```yaml
command:
Expand Down
Loading