From e5a2b42e6ade646cd8d403f409823f642aaed955 Mon Sep 17 00:00:00 2001 From: Gabriel Terwesten Date: Sun, 5 Feb 2023 11:07:33 +0100 Subject: [PATCH] docs: take advantage of new `docs.page` features (#464) --- README.md | 76 +---------------------- docs/commands/bootstrap.mdx | 82 +++++++++++++++++-------- docs/commands/clean.mdx | 17 ++++-- docs/commands/exec.mdx | 23 +++---- docs/commands/list.mdx | 7 ++- docs/commands/publish.mdx | 21 ++++--- docs/commands/run.mdx | 2 +- docs/commands/version.mdx | 67 ++++++++++++-------- docs/configuration/overview.mdx | 98 +++++++++++++----------------- docs/configuration/scripts.mdx | 26 ++++---- docs/environment-variables.mdx | 43 +++++++++---- docs/filters.mdx | 2 +- docs/guides/automated-releases.mdx | 31 +++++----- docs/guides/migrations.mdx | 18 +++--- docs/ide-support.mdx | 16 +++-- docs/index.mdx | 48 ++++++++++++--- packages/melos/README.md | 87 +++++++++++++------------- 17 files changed, 349 insertions(+), 315 deletions(-) mode change 100644 => 120000 README.md diff --git a/README.md b/README.md deleted file mode 100644 index c65a38e5d..000000000 --- a/README.md +++ /dev/null @@ -1,75 +0,0 @@ - -

- - Melos

- - A tool for managing Dart projects with multiple packages, inspired by Lerna. -

- -

- Melos - docs.page - - Chat on Discord - -

- - -

- Documentation • - License -

- -### About - -Splitting up large code bases into separate independently versioned packages is extremely useful for code sharing. However, making changes across many repositories is messy and difficult to track, and testing across repositories gets complicated really fast. - -To solve these (and many other) problems, some projects will organize their code bases into multi-package repositories (sometimes called [monorepos](https://en.wikipedia.org/wiki/Monorepo)). - -**Melos is a tool that optimizes the workflow around managing multi-package repositories with git and Pub.** - -### What can Melos do? - -- 🔗 Override `pub get` in development to install packages in your workspace from path _without having to edit your `pubspec.yaml`_. -- 📦 Automatically version, create changelogs and publish your packages using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). -- 📜 Pre-define advanced custom scripts for your workspace in your melos.yaml configuration to use via `melos run [scriptName]`. Anyone contributing to your workspace can just run melos run to be prompted to select a script from a list with descriptions of each script. - - Scripts can even [prompt to select a package](https://github.com/invertase/melos/pull/34) to run against with pre-defined filters. -- ⚡ Execute commands across your packages easily with melos exec -- command here with additional concurrency and fail-fast options. - - [Environment variables](https://github.com/invertase/melos/issues/3) containing various information about the current package and the workspace are available in each execution. - - Can be combined with all package filters. -- 🎯 Many advanced package filtering options allowing you to target specific packages or groups of packages in your workspace. -- ♨️ Advanced support for IntelliJ IDEs with automatic creation of [run configurations for workspace defined scripts and more](https://github.com/invertase/melos/issues/9) on workspace bootstrap. - - Integration with VS Code through an [extension][melos-code]. - -## Install - -```bash -dart pub global activate melos -``` - -## How to Contribute - -To start making contributions please refer to [`CONTRIBUTING.md`](./CONTRIBUTING.md). - -## README Badge - -Using Melos? Add a README badge to show it off: - -[![melos](https://img.shields.io/badge/maintained%20with-melos-f700ff.svg?style=flat-square)](https://github.com/invertase/melos) - -```markdown -[![melos](https://img.shields.io/badge/maintained%20with-melos-f700ff.svg?style=flat-square)](https://github.com/invertase/melos) -``` - ---- - -

- - - -

- Built and maintained by Invertase. -

-

- -[melos-code]: https://marketplace.visualstudio.com/items?itemName=blaugold.melos-code diff --git a/README.md b/README.md new file mode 120000 index 000000000..aa79e4806 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +./packages/melos/README.md \ No newline at end of file diff --git a/docs/commands/bootstrap.mdx b/docs/commands/bootstrap.mdx index de2701ae2..bd7963178 100644 --- a/docs/commands/bootstrap.mdx +++ b/docs/commands/bootstrap.mdx @@ -1,13 +1,14 @@ --- title: Bootstrap Command -description: "Learn more about the `bootstrap` command in Melos." +description: Learn more about the `bootstrap` command in Melos. --- # Bootstrap Command -> Supports all [Melos filtering](/filters) flags. +Supports all [Melos filtering](/filters) flags. -This command initializes the workspace, links local packages together and installs remaining package dependencies. +This command initializes the workspace, links local packages together and +installs remaining package dependencies. ```bash melos bootstrap @@ -18,33 +19,64 @@ melos bs Bootstrapping has two primary functions: 1. Installing all package dependencies (internally using `pub get`). -2. Locally linking any packages together via path dependency overrides _without having to edit your pubspec.yaml_. +2. Locally linking any packages together via path dependency overrides _without + having to edit your pubspec.yaml_. ## Why is bootstrapping required? -In normal projects, packages can be linked by providing a `path` within the `pubspec.yaml`. This works for small -projects however presents a problem at scale. Packages cannot be published with a locally defined path, meaning -once you're ready to publish your packages you'll need to manually update all the packages `pubspec.yaml` files -with the versions. If your packages are also tightly coupled (dependencies of each other), you'll also have to manually -check which versions should be updated. Even with a few of packages this can become a long and error-prone task. +In normal projects, packages can be linked by providing a `path` within the +`pubspec.yaml`. This works for small projects however presents a problem at +scale. Packages cannot be published with a locally defined path, meaning once +you're ready to publish your packages you'll need to manually update all the +packages `pubspec.yaml` files with the versions. If your packages are also +tightly coupled (dependencies of each other), you'll also have to manually check +which versions should be updated. Even with a few of packages this can become a +long and error-prone task. -Melos solves this problem by overriding local files which the Dart analyzer uses to read packages from. If a local package -exists (defined in the `melos.yaml` file) and a different local package has it listed as a dependency, it will be linked -regardless of whether a version has been specified. +Melos solves this problem by overriding local files which the Dart analyzer uses +to read packages from. If a local package exists (defined in the `melos.yaml` +file) and a different local package has it listed as a dependency, it will be +linked regardless of whether a version has been specified. ### Benefits -- All local packages in the repository can be interlinked by Melos to point to their local directories rather than 'remote' _without pubspec.yaml modifications_. - - **Example Scenario**: In a repository, package `A` depends on package `B`. Both packages `A` & `B` exist in the monorepo. However, if you `pub get` inside package `A`, `pub` will retrieve package `B` from the pub.dev registry as it's unaware of `B` existing locally. However, with Melos, it's aware that package `B` exists locally too, so it will generate the various pub files to point to a relative path in the local repository. - - If you wanted to use pub you could of course define a dependency override in the pubspec of package `A` that sets a path for package `B` but, then you'd have to do this manually every time and then manually remove it again when you want to publish or even commit your changes. This doesn't scale well and doesn't help with making a repository contributor friendly. [FlutterFire](https://github.com/FirebaseExtended/flutterfire) for example has over 40 packages with various interlinking levels (try run `melos list --graph` to see its local dependency graph). - - This can also get phenomenally worse for example say if we introduce package `C` that package `B` depends on but package `C` then also depends on `A`. +- All local packages in the repository can be interlinked by Melos to point to + their local directories rather than 'remote' _without pubspec.yaml + modifications_. + - **Example Scenario**: In a repository, package `A` depends on package `B`. + Both packages `A` & `B` exist in the monorepo. However, if you `pub get` + inside package `A`, `pub` will retrieve package `B` from the pub.dev + registry as it's unaware of `B` existing locally. However, with Melos, it's + aware that package `B` exists locally too, so it will generate the various + pub files to point to a relative path in the local repository. + - If you wanted to use pub you could of course define a dependency override + in the pubspec of package `A` that sets a path for package `B` but, then + you'd have to do this manually every time and then manually remove it + again when you want to publish or even commit your changes. This doesn't + scale well and doesn't help with making a repository contributor friendly. + [FlutterFire](https://github.com/FirebaseExtended/flutterfire) for example + has over 40 packages with various interlinking levels (try run + `melos list --graph` to see its local dependency graph). + - This can also get phenomenally worse for example say if we introduce + package `C` that package `B` depends on but package `C` then also + depends on `A`. - Interlinking highlights dart/analyzer issues early. - - **Example Scenario**: Package `A` relies on package `B` from the same mono repo. Package `B` gets a minor API change. Via `pub get` on package `A` the dart analyzer and IDEs report no issues with the package as it installed package `B` from the remote pub registry and not local (which hasn't been published yet). With Melos, the dart analyzer / IDEs would highlight this issue immediately since local versions are used. The same applies for non-breaking deprecations, package `A` wouldn't show there was a deprecated API in use without being interlinked through Melos. -- Interlinking allows working on new, not yet published (or private) packages easily, without defining dependency overrides. + - **Example Scenario**: Package `A` relies on package `B` from the same mono + repo. Package `B` gets a minor API change. Via `pub get` on package `A` the + dart analyzer and IDEs report no issues with the package as it installed + package `B` from the remote pub registry and not local (which hasn't been + published yet). With Melos, the dart analyzer / IDEs would highlight this + issue immediately since local versions are used. The same applies for + non-breaking deprecations, package `A` wouldn't show there was a deprecated + API in use without being interlinked through Melos. +- Interlinking allows working on new, not yet published (or private) packages + easily, without defining dependency overrides. ## Combining with filters -Bootstrap supports [all package filtering options](/filters), therefore if you wanted to you could bootstrap only a specific subset of your packages, for example: +Bootstrap supports [all package filtering options](/filters), therefore if you +wanted to you could bootstrap only a specific subset of your packages, for +example: ```bash # Only bootstrap packages that have @@ -54,10 +86,11 @@ melos bootstrap --diff="main" ## Adding a postbootstrap lifecycle script -Melos supports various command [lifecycle hooks](/configuration/scripts#hooks) that can be defined in your `melos.yaml`. +Melos supports various command [lifecycle hooks](/configuration/scripts#hooks) +that can be defined in your `melos.yaml`. -For example, if you needed to run something such as a build runner automatically after `melos bootstrap` is run, you can add a -`postBootstrap` script: +For example, if you needed to run something such as a build runner automatically +after `melos bootstrap` is run, you can add a `postBootstrap` script: ```yaml # melos.yaml @@ -67,5 +100,6 @@ scripts: # ... ``` -This is useful to ensure any local project requirements, such as generated files being built, are met when anyone is working on -your mono repo code base, e.g. external contributors. +This is useful to ensure any local project requirements, such as generated files +being built, are met when anyone is working on your mono repo code base, e.g. +external contributors. diff --git a/docs/commands/clean.mdx b/docs/commands/clean.mdx index 79681d03d..128352651 100644 --- a/docs/commands/clean.mdx +++ b/docs/commands/clean.mdx @@ -1,13 +1,14 @@ --- title: Clean Command -description: "Learn more about the `clean` command in Melos." +description: Learn more about the `clean` command in Melos. --- # Clean Command -> Supports all [Melos filtering](/filters) flags. +Supports all [Melos filtering](/filters) flags. -This command cleans the current workspace and all its packages of temporary pub & generated Melos IDE files. +This command cleans the current workspace and all its packages of temporary pub +& generated Melos IDE files. ```bash melos clean @@ -32,7 +33,8 @@ melos bootstrap ## Combining with filters -Clean supports [all package filtering options](/filters), therefore if you wanted to you could clean only a specific subset of your packages, for example: +Clean supports [all package filtering options](/filters), therefore if you +wanted to you could clean only a specific subset of your packages, for example: ```bash # Only clean Flutter packages or apps. @@ -41,9 +43,12 @@ melos clean --flutter ## Adding a postclean lifecycle script -Melos supports various command lifecycle hooks that can be defined in your `melos.yaml`. +Melos supports various command lifecycle hooks that can be defined in your +`melos.yaml`. -For example, if you needed to cleanup any generated files, e.g. from a build runner, automatically after `melos clean` is ran, you can add a `postClean` script. +For example, if you needed to cleanup any generated files, e.g. from a build +runner, automatically after `melos clean` is ran, you can add a `postClean` +script. ```yaml # melos.yaml diff --git a/docs/commands/exec.mdx b/docs/commands/exec.mdx index 5874e0cb6..741e5acdf 100644 --- a/docs/commands/exec.mdx +++ b/docs/commands/exec.mdx @@ -1,11 +1,11 @@ --- title: Exec Command -description: "Learn more about the `exec` command in Melos." +description: Learn more about the `exec` command in Melos. --- # Exec Command -> Supports all [Melos filtering](/filters) flags. +Supports all [Melos filtering](/filters) flags. Execute an arbitrary command in each package. @@ -14,22 +14,23 @@ melos exec # e.g. melos exec -- pub global run tuneup check ``` -The command is executed in a shell. On Windows the shell is `cmd.exe` and on all other platforms -it is `sh`. +The command is executed in a shell. On Windows the shell is `cmd.exe` and on all +other platforms it is `sh`. -If multiple commands are being executed and no further commands should be executed -after a command has failed, connect the commands with `&&`: +If multiple commands are being executed and no further commands should be +executed after a command has failed, connect the commands with `&&`: ```shell melos exec -- "melos bootstrap && melos run build" ``` -It is important to pass multiple commands as a single string to `melos exec`, otherwise the shell -will pass only the first command to `melos exec`. +It is important to pass multiple commands as a single string to `melos exec`, +otherwise the shell will pass only the first command to `melos exec`. ## concurrency (-c) -Defines the max concurrency value of how many packages will execute the command in at any one time. Defaults to `5`. +Defines the max concurrency value of how many packages will execute the command +in at any one time. Defaults to `5`. ```bash # Set a 1 concurrency @@ -38,8 +39,8 @@ melos exec -c 1 -- "dart analyze ." ## --fail-fast -Whether exec should fail fast and not execute the script in further packages if the script fails in an individual package. -Defaults to `false`. +Whether exec should fail fast and not execute the script in further packages if +the script fails in an individual package. Defaults to `false`. ```bash # Fail fast diff --git a/docs/commands/list.mdx b/docs/commands/list.mdx index ea7b3d864..21c188c01 100644 --- a/docs/commands/list.mdx +++ b/docs/commands/list.mdx @@ -1,11 +1,11 @@ --- title: List Command -description: "Learn more about the `list` command in Melos." +description: Learn more about the `list` command in Melos. --- # List Command -> Supports all [Melos filtering](/filters) flags. +Supports all [Melos filtering](/filters) flags. List information about the local packages. @@ -33,7 +33,8 @@ melos list -a ## --relative (-r) -When printing output, use package paths relative to the root of the workspace. Defaults to `false` (or full paths). +When printing output, use package paths relative to the root of the workspace. +Defaults to `false` (or full paths). ```bash melos list --relative diff --git a/docs/commands/publish.mdx b/docs/commands/publish.mdx index 7c2b6f6ec..cf354c149 100644 --- a/docs/commands/publish.mdx +++ b/docs/commands/publish.mdx @@ -1,13 +1,14 @@ --- title: Publish Command -description: "Learn more about the `publish` command in Melos." +description: Learn more about the `publish` command in Melos. --- # Publish Command -> Supports all [Melos filtering](/filters) flags. +Supports all [Melos filtering](/filters) flags. -Publish any unpublished packages or package versions in your repository to pub.dev. `dry-run` is enabled by default. +Publish any unpublished packages or package versions in your repository to +pub.dev. `dry-run` is enabled by default. ```bash melos publish @@ -15,7 +16,8 @@ melos publish ## --dry-run -Flags whether to publish the packages as a dry run (validate but do not publish). Defaults to `true`. +Flags whether to publish the packages as a dry run (validate but do not +publish). Defaults to `true`. ```bash # Publish packages with dry run @@ -27,7 +29,8 @@ melos publish --no-dry-run Use `--no-dry-run` to disable. -Publish any unpublished packages or package versions in your repository to pub.dev. `dry-run` is enabled by default. +Publish any unpublished packages or package versions in your repository to +pub.dev. `dry-run` is enabled by default. ```bash melos publish @@ -35,10 +38,14 @@ melos publish ## --git-tag-version (-t) -Add any missing git tags for release. Tags are only created if --no-dry-run is also set. +Add any missing git tags for release. Tags are only created if --no-dry-run is +also set. ```bash melos publish --no-dry-run --git-tag-version ``` -Note that tags are automatically created as part of `melos version` (unless `--no-git-tag-version` is specified when running the version command) so this is usually not required on `melos publish` unless you're doing a manual version and publish of packages. +Note that tags are automatically created as part of `melos version` (unless +`--no-git-tag-version` is specified when running the version command) so this is +usually not required on `melos publish` unless you're doing a manual version and +publish of packages. diff --git a/docs/commands/run.mdx b/docs/commands/run.mdx index 404ca77f7..65aa288fe 100644 --- a/docs/commands/run.mdx +++ b/docs/commands/run.mdx @@ -1,6 +1,6 @@ --- title: Run Command -description: 'Learn more about the `run` command in Melos.' +description: Learn more about the `run` command in Melos. --- # Run Command diff --git a/docs/commands/version.mdx b/docs/commands/version.mdx index ee856ac5e..d60aac84f 100644 --- a/docs/commands/version.mdx +++ b/docs/commands/version.mdx @@ -1,33 +1,36 @@ --- title: Version Command -description: "Learn more about the `version` command in Melos." +description: Learn more about the `version` command in Melos. --- # Version Command -> Supports all [Melos filtering](/filters) flags. +Supports all [Melos filtering](/filters) flags. Automatically version and generate changelogs for all packages. - ```bash melos version ``` -> To learn more, visit the [Automated Releases](/guides/automated-releases) documentation. + + To learn more, visit the [Automated Releases](/guides/automated-releases) + documentation. + ## Hooks -The `version` command supports the following hooks in addition to the [default hooks](/configuration/scripts#hooks): - -- `preVersionCommit`: Runs before the version commit is created. - Allows you to make your own changes as part of versioning. - You need to stage changes that you make yourself. +The `version` command supports the following hooks in addition to the +[common hooks](/configuration/scripts#hooks): +- `preVersionCommit`: Runs before the version commit is created. Allows you to + make your own changes as part of versioning. You need to stage changes that + you make yourself. ## --prerelease (-p) -Version any packages with changes as a prerelease. Cannot be combined with graduate flag. Defaults to `false`. +Version any packages with changes as a prerelease. Cannot be combined with +graduate flag. Defaults to `false`. ```bash melos version --prerelease @@ -36,7 +39,9 @@ melos version -p ## --graduate (-g) -Graduate current prerelease versioned packages to stable versions, e.g. "0.10.0-dev.1" becomes "0.10.0". Cannot be combined with prerelease flag. Defaults to `false`. +Graduate current prerelease versioned packages to stable versions, e.g. +"0.10.0-dev.1" becomes "0.10.0". Cannot be combined with prerelease flag. +Defaults to `false`. ```bash melos version --graduate @@ -45,7 +50,8 @@ melos version -g ## --[no-]changelog (-c) -Update CHANGELOG.md files (based on conventional commit messages). Defaults to `true`. +Update CHANGELOG.md files (based on conventional commit messages). Defaults to +`true`. ```bash melos version --changelog @@ -67,8 +73,8 @@ Use `--no-git-tag-version` to disable. ## --[no-]release-url (-r) -Generate and print a link to the prefilled release creation page for each package after versioning. -Defaults to `false`. +Generate and print a link to the prefilled release creation page for each +package after versioning. Defaults to `false`. ```bash melos version --release-url @@ -78,12 +84,14 @@ melos version -r Use `--no-release-url` to disable. The default for this option can be configured in -[command/version/releaseUrl](/configuration/overview#commandversionreleaseUrl) in your `melos.yaml` -file. +[command/version/releaseUrl](/configuration/overview#releaseurl) in your +`melos.yaml` file. ## --[no-]dependent-constraints -Update dependency version constraints of packages in this workspace that depend on any of the packages that will be updated with this versioning run. (defaults to on) +Update dependency version constraints of packages in this workspace that depend +on any of the packages that will be updated with this versioning run. (defaults +to on) ```bash melos version --no-dependent-constraints @@ -93,7 +101,9 @@ Use `--no-dependent-constraints` to disable. ## --[no-]dependent-versions -Make a new patch version and changelog entry in packages that are updated due to "--dependent-constraints" changes. Only usable with "--dependent-constraints" enabled and Conventional Commits based versioning. (defaults to on) +Make a new patch version and changelog entry in packages that are updated due to +"--dependent-constraints" changes. Only usable with "--dependent-constraints" +enabled and Conventional Commits based versioning. (defaults to on) ```bash melos version --no-dependent-versions @@ -112,7 +122,10 @@ melos version -a ## --preid -When run with this option, `melos version` will increment prerelease versions using the specified prerelease identifier, e.g. using a "beta" preid along with the --prerelease flag would result in a version in the format "1.0.0-1.0.beta.0". Applies only to Conventional Commits based versioning. +When run with this option, `melos version` will increment prerelease versions +using the specified prerelease identifier, e.g. using a "beta" preid along with +the --prerelease flag would result in a version in the format +"1.0.0-1.0.beta.0". Applies only to Conventional Commits based versioning. ```bash melos version --prerelease --preid=beta @@ -120,9 +133,10 @@ melos version --prerelease --preid=beta ## --dependent-preid -This option is the same as --preid, but only applies to packages that are versioned due to a -change in a dependency version. When this option is not provided but the --preid option is, the -value of the --preid option will be used instead. +This option is the same as --preid, but only applies to packages that are +versioned due to a change in a dependency version. When this option is not +provided but the --preid option is, the value of the --preid option will be used +instead. ```bash melos version --prerelease --dependent-preid=beta @@ -130,7 +144,9 @@ melos version --prerelease --dependent-preid=beta ## --message (-m) -Override the release's commit message. If the message contains `{new_package_versions}`, it will be replaced by the list of newly versioned package names. If --message is not provided, the message will default to: +Override the release's commit message. If the message contains +`{new_package_versions}`, it will be replaced by the list of newly versioned +package names. If --message is not provided, the message will default to: ``` chore(release): publish packages @@ -146,7 +162,10 @@ melos version --message="chore(release): publish new versions" ## --manual-version (-V) -Manually specify a version change for a package. Can be used multiple times. Each value must be in the format `:`. Cannot be combined with --graduate or --prerelease flag. +Manually specify a version change for a package. Can be used multiple times. +Each value must be in the format +`:`. Cannot be combined with +--graduate or --prerelease flag. ```bash melos version --manual-version=foo:patch diff --git a/docs/configuration/overview.mdx b/docs/configuration/overview.mdx index aa849709f..16ad4cb70 100644 --- a/docs/configuration/overview.mdx +++ b/docs/configuration/overview.mdx @@ -12,9 +12,9 @@ Additionally, projects may include a `melos_overrides.yaml` file to override any `melos.yaml` field. This is useful for making untracked customizations to a project. -## `name` +## name -> required +Required The name of this project for display purposes within IO environments and IDEs. @@ -22,7 +22,7 @@ The name of this project for display purposes within IO environments and IDEs. name: My Awesome Project ``` -## `repository` +## repository The URL of the git repository that contains the Melos workspace. @@ -46,9 +46,7 @@ repository: name: melos ``` -## `sdkPath` - -> optional +## sdkPath Path to the Dart/Flutter SDK that should be used. @@ -67,9 +65,9 @@ highest to lowest is: sdkPath: .fvm/flutter_sdk ``` -## `packages` +## packages -> required +Required 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. @@ -84,8 +82,10 @@ packages: - 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. + Avoid recursive whildcards (`**`) as they require walking large parts of the file system and can be slow. If you have packages at multiple levels of depth, @@ -97,9 +97,7 @@ packages: - packages/*/example ``` -## `ignore` - -> optional +## ignore 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. @@ -110,16 +108,16 @@ ignore: - 'packages/**/example' ``` -> You can also expand the scope of ignored packages on a per-command basis via -> the [`--scope` filter](/filters#scope) flag. - -## `ide` + + You can also expand the scope of packages on a per-command basis via the + [`--scope` filter](/filters#--scope) flag. + -> optional +## ide/intellij -Configuration for realting to IDE support. +Configuration realting to IntelliJ IDE support. -## `ide/intellij/enabled` +### enabled Whether to generate IntelliJ IDEA config files to improve the developer experience when working in a Melos workspace. @@ -129,10 +127,10 @@ The default is `true`. ```yaml ide: intellij: - enabled: false # set to false to override default and disable + enabled: false ``` -## `ide/intellij/moduleNamePrefix` +### 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 @@ -140,28 +138,18 @@ collisions with other IntelliJ modules you may already have in place. The default is 'melos\_'. -## `scripts` - -> optional +## scripts 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` +## command/bootstrap Configuration for the `bootstrap` command. -### `command/bootstrap/dependencyOverridePaths` - -> optional +### dependencyOverridePaths A list of paths to local packages realtive to the workspace directory that should be added to each workspace package's dependency overrides. Each entry can @@ -175,13 +163,13 @@ dependencyOverridePaths: - '../external_project/packages/**' ``` -### `command/bootstrap/runPubGetInParallel` +### runPubGetInParallel Whether to run `pub get` in parallel during bootstrapping. The default is `true`. -### `command/bootstrap/runPubGetOffline` +### runPubGetOffline Whether to attempt to run `pub get` in offline mode during bootstrapping. @@ -189,11 +177,11 @@ Useful in closed network environments with pre-populated pubcaches. The default is `false`. -### `command/version` +## command/version Configuration for the `version` command. -### `command/version/message` +### message A template for the commit message, that is generated by `melos version`. @@ -219,7 +207,7 @@ command: {new_package_versions} ``` -### `command/version/branch` +### branch If specified, prevents `melos version` from being used inside branches other than the one specified. @@ -230,7 +218,7 @@ command: branch: main ``` -### `command/version/includeScopes` +### includeScopes Whether to include conventional commit scopes in the generated CHANGELOG.md. Defaults to `true`. @@ -238,10 +226,10 @@ Defaults to `true`. ```yaml command: version: - includeScopes: true + includeScopes: false ``` -### `command/version/includeCommitId` +### includeCommitId Whether to add short commit ids to commits (no links) in the CHANGELOG.md that is generated by `melos version`. @@ -252,7 +240,7 @@ command: includeCommitId: true ``` -### `command/version/linkToCommits` +### linkToCommits Whether to add links to commits in the CHANGELOG.md that is generated by `melos version`. Defaults to `true` if `repository` is specified. @@ -263,10 +251,10 @@ Enabling this option, requires ```yaml command: version: - linkToCommits: true + linkToCommits: false ``` -### `command/version/workspaceChangelog` +### workspaceChangelog Whether to additionally build a CHANGELOG.md at the root of the workspace when running `melos version`. Defaults to `true`. @@ -274,10 +262,10 @@ running `melos version`. Defaults to `true`. ```yaml command: version: - workspaceChangelog: true + workspaceChangelog: false ``` -### `command/version/changelogs` +### changelogs Configure aggregate changelogs which document the changes made to multiple packages. @@ -293,11 +281,11 @@ command: scope: foo_* ``` -### `command/version/changelogs/path` +#### path The path to the changelog file relative to the workspace root. -### `command/version/changelogs/packageFilters` +#### packageFilters Package filters to match packages that should be included in the changelog. @@ -308,16 +296,14 @@ See [Filtering Packages](/filters) for all available filters. equivalent of the command line option `--file-exists` use `fileExists`. -### `command/version/changelogs/description` - -> optional +#### description A description to include at the top of the changelog. If you change this value, you will need to manually update the changelog file to reflect the new description. -### `command/version/updateGitTagRefs` +### updateGitTagRefs Whether to update package version tags in git dependencies of dependents when versioning packages. @@ -332,14 +318,14 @@ command: updateGitTagRefs: true ``` -### `command/version/releaseUrl` +### releaseUrl Whether to generate and print a link to the prefilled release creation page for each package after versioning. Defaults to `false`. [glob]: https://docs.python.org/3/library/glob.html -### `command/version/fetchTags` +### fetchTags Whether to fetch tags from the `origin` remote before versioning. Defaults to `true`. diff --git a/docs/configuration/scripts.mdx b/docs/configuration/scripts.mdx index 4fd60b48c..bbb4d3d7c 100644 --- a/docs/configuration/scripts.mdx +++ b/docs/configuration/scripts.mdx @@ -23,7 +23,7 @@ The extends syntax allows for a more complex configuration of a script: scripts: hello: name: hey - description: 'Greet the world' + description: Greet the world run: echo '$GREETING World' env: GREETING: 'Hey' @@ -40,19 +40,19 @@ scripts: prepare: melos bootstrap && melos run build ``` -## `scripts/*/name` +## name A unique identifier for the script. -## `scripts/*/description` +## description A short description, shown when using `melos run` with no argument. -## `scripts/*/run` +## run The command to execute. -## `scripts/*/exec` +## exec Execute a script in multiple packages through `melos exec`. @@ -79,20 +79,20 @@ scripts: concurrency: 1 ``` -See the [`packageFilters`](/configuration/scripts#scriptspackagefilters) option -for filtering the packages to execute the command in. +See the [`packageFilters`](/configuration/scripts#packagefilters) option for +filtering the packages to execute the command in. -## `scripts/*/exec/concurrency` +### concurrency Defines the max concurrency value of how many packages will execute the command in at any one time. Defaults to `5`. -## `scripts/*/exec/failFast` +### failFast Whether `exec` should fail fast and not execute the script in further packages if the script fails in an individual package. Defaults to `false`. -## `scripts/*/exec/orderDependents` +### orderDependents Whether `exec` should order the execution of the script in multiple packages based on the dependency graph of the packages. The script will be executed in @@ -100,11 +100,11 @@ leaf packages first and then in packages that depend on them and so on. This is useful for example, for a script that generates code in multiple packages, which depend on each other. Defaults to `false`. -## `scripts/*/env` +## env A map of environment variables that will be passed to the executed command. -## `scripts/*/packageFilters` +## packageFilters The [`melos exec`](/commands/exec) command allows you to execute a command for multiple packages. When used in a script, you can declare filter options in the @@ -133,7 +133,7 @@ the script in all packages, use the `--no-select` option. --- -# Hooks +## Hooks Certain Melos commands support running scripts before and after the command is executed, as well as at other interstring points in the command's execution. diff --git a/docs/environment-variables.mdx b/docs/environment-variables.mdx index 553b9dd2f..60f881b08 100644 --- a/docs/environment-variables.mdx +++ b/docs/environment-variables.mdx @@ -1,11 +1,16 @@ --- title: Environment Variables -description: Learn more about all the environment variables Melos supports and also pre-populates. +description: + Learn more about all the environment variables Melos supports and also + pre-populates. --- # Environment Variables -These variables are available as environment variables in scripts run by `melos exec`. They can also automatically replaced/injected on `melos exec` commands e.g. `melos exec --file-exists="./test_driver/MELOS_PARENT_PACKAGE_NAME_e2e.dart" --scope="*example*" -- echo hello` +These variables are available as environment variables in scripts run by +`melos exec`. They can also automatically replaced/injected on `melos exec` +commands e.g. +`melos exec --file-exists="./test_driver/MELOS_PARENT_PACKAGE_NAME_e2e.dart" --scope="*example*" -- echo hello` ## Defined by Melos @@ -15,41 +20,53 @@ The path to the mono-repo root ### `MELOS_PACKAGE_NAME` -The name of the package that's currently executing a script (when using `melos exec`) +The name of the package that's currently executing a script (when using +`melos exec`) ### `MELOS_PACKAGE_VERSION` -The version of the package that's currently executing a script (when using `melos exec`) +The version of the package that's currently executing a script (when using +`melos exec`) ### `MELOS_PACKAGE_PATH` -The path of the package that's currently executing a script (when using `melos exec`). +The path of the package that's currently executing a script (when using +`melos exec`). ### `MELOS_PARENT_PACKAGE_NAME` -The name of the parent package of the current package that's currently executing a script (when using `melos exec`). +The name of the parent package of the current package that's currently executing +a script (when using `melos exec`). ### `MELOS_PARENT_PACKAGE_VERSION` -The version of the parent package of the current package that's currently executing a script (when using `melos exec`). +The version of the parent package of the current package that's currently +executing a script (when using `melos exec`). ### `MELOS_PARENT_PACKAGE_PATH` -The path of the parent package of the current package that's currently executing a script (when using `melos exec`). +The path of the parent package of the current package that's currently executing +a script (when using `melos exec`). #### What is a 'parent package' -If a package exists in a directory that is also a child of another package, then its parent is the 'parent package'. For example; the package `firebase_auth` has a `example` directory that is also a package, when running a `melos exec` script in the `example` package then the parent package would be `firebase_auth`. +If a package exists in a directory that is also a child of another package, then +its parent is the 'parent package'. For example; the package `firebase_auth` has +a `example` directory that is also a package, when running a `melos exec` script +in the `example` package then the parent package would be `firebase_auth`. -Note, this 'parent package' functionality only currently works when the 'child package' name ends with `example` +Note, this 'parent package' functionality only currently works when the 'child +package' name ends with `example` ## User Defined ### `MELOS_PACKAGES` -Define a comma delimited list of package names that Melos should focus on. This bypasses all filtering flags if defined. +Define a comma delimited list of package names that Melos should focus on. This +bypasses all filtering flags if defined. ### `MELOS_SDK_PATH` -The path to the Dart/Flutter SDK to use. This environment variable has precedence over the `sdkPath` -option in `melos.yaml`, but is overridden by the command line option `--sdk-path`. +The path to the Dart/Flutter SDK to use. This environment variable has +precedence over the `sdkPath` option in `melos.yaml`, but is overridden by the +command line option `--sdk-path`. diff --git a/docs/filters.mdx b/docs/filters.mdx index cfa64fa27..ecb738ee1 100644 --- a/docs/filters.mdx +++ b/docs/filters.mdx @@ -1,6 +1,6 @@ --- title: Filtering Packages -description: 'Learn more about all the package filtering flags in Melos.' +description: Learn more about all the package filtering flags in Melos. --- # Filtering Packages diff --git a/docs/guides/automated-releases.mdx b/docs/guides/automated-releases.mdx index 788437663..7bc80d89f 100644 --- a/docs/guides/automated-releases.mdx +++ b/docs/guides/automated-releases.mdx @@ -41,8 +41,8 @@ steps: 1. Apply [filters](/filters) to the list of workspace packages. 2. Load the commit history for each package. If the `--diff` option is - specified, Melos will only load the specified commit. Otherwise - it will load all commits since the last version tag (e.g. `foo-v1.0.0`). + specified, Melos will only load the specified commit. Otherwise it will load + all commits since the last version tag (e.g. `foo-v1.0.0`). 3. Parse commit messages as Conventional Commits. If a commit message does not follow the Conventional Commits specification, it will be ignored. 4. Filter out commits with types that don't trigger a version bump. For example, @@ -157,9 +157,9 @@ section for the new version. You can disable this behavior by passing See the [configuration options](/configuration/overview#commandversion) for the `version` command for customizing changelog generation. -Optionally, Melos can also write a -[workspace changelog](/configuration/overview#commandversionworkspacechangelog). -This is disabled by default. +Melos can also write a +[workspace changelog](/configuration/overview#workspacechangelog). This is +enabled by default. ## Publishing @@ -168,7 +168,7 @@ To publish packages on [pub.dev](https://pub.dev) you must: 1. Have permission to publish all the packages. 2. Be on a machine which is authenticated with Pub. -> Internally, Melos uses `pub publish` to publish the packages. +Internally, Melos uses `pub publish` to publish the packages. Once you have [versioned](/guides/automated-releases#versioning) your packages, run the publish command to check everything is good to go: @@ -212,7 +212,11 @@ If your packages are private and you don't publish them to your `pubspec.yaml` files and Melos will ensure that the tags are updated accordingly. -Example: +To use this feature enable +[`command/version/updateGitTagRefs`](/configuration/overview#updategittagrefs) +in `melos.yaml` + +Take the following git dependency: ```yaml dependencies: @@ -221,9 +225,12 @@ dependencies: url: git@github.com:org/repo.git path: packages/internal_dep ref: internal_dep-v0.0.1 +``` -# will be updated to: +When creating a patch release for `internal_dep` through `melos version` the +`ref` would be updated to the new version: +```yaml dependencies: internal_dep: git: @@ -231,11 +238,3 @@ dependencies: path: packages/internal_dep ref: internal_dep-v0.0.2 ``` - -To use this feature enable it in `melos.yaml` - -```yaml -command: - version: - updateGitTagRefs: true # defaults to false -``` diff --git a/docs/guides/migrations.mdx b/docs/guides/migrations.mdx index 6a6d7f6ca..b90a406dd 100644 --- a/docs/guides/migrations.mdx +++ b/docs/guides/migrations.mdx @@ -69,14 +69,14 @@ can be used to specify a range of commits in addition to a single commit. To migrate from `--since` to `--diff` simply replace `--since` with `--diff`. -### Options that are now enabled by default +### Changed option defaults -The following options which were previously set to `false` by default are now -set to `true` by default: +The following options are now enabled by default: -- `command/version/includeScopes` -- `command/version/linkToCommits`, if `repository` is configured -- `command/version/workspaceChangelog` +- [`command/version/includeScopes`](/configuration/overview#includescopes) +- [`command/version/linkToCommits`](/configuration/overview#linktocommits), if + [`repository`](/configuration/overview#repository) is configured +- [`command/version/workspaceChangelog`](/configuration/overview#workspacechangelog) ### Lifecycle hooks @@ -101,8 +101,10 @@ created and is the equivalent of the previous `version` hook. ### Package filters -The `select-package` option for scripts has been renamed to `packageFilters`. -This brings it in line with `command/version/changelogs/packageFilters`. +The `select-package` option for scripts has been renamed to +[`packageFilters`](/configuration/scripts#packagefilters). This brings it in +line with +[`command/version/changelogs/packageFilters`](/configuration/overview#packagefilters). The names of filters specified in `packageFilters` are now camel cased instead of kebab cased. diff --git a/docs/ide-support.mdx b/docs/ide-support.mdx index 6689646f8..f41ffbabf 100644 --- a/docs/ide-support.mdx +++ b/docs/ide-support.mdx @@ -1,6 +1,8 @@ --- title: IDE Support -description: "Learn more about the IDE integration features Melos provides for IntelliJ and VS Code." +description: + 'Learn more about the IDE integration features Melos provides for IntelliJ and + VS Code.' --- # IDE Support @@ -8,11 +10,12 @@ description: "Learn more about the IDE integration features Melos provides for I ## IntelliJ Melos integrates with IntelliJ via the generation of -[IntelliJ project module](https://www.jetbrains.com/help/idea/creating-and-managing-modules.html) files (`.iml` files) -during `melos bootstrap`. +[IntelliJ project module](https://www.jetbrains.com/help/idea/creating-and-managing-modules.html) +files (`.iml` files) during `melos bootstrap`. -Melos will create an IntelliJ project module for each package in your Melos workspace, and will create flutter and dart Run -configurations for your `main.dart`s and your package's test suite. +Melos will create an IntelliJ project module for each package in your Melos +workspace, and will create flutter and dart Run configurations for your +`main.dart`s and your package's test suite. ![Generated Run configurations](/assets/intellij-run-configurations.png) @@ -67,4 +70,5 @@ the `Melos: Show package graph` command. ![Show package graph in VS Code](/assets/vs-code-package-graph.png) -[melos-code]: https://marketplace.visualstudio.com/items?itemName=blaugold.melos-code +[melos-code]: + https://marketplace.visualstudio.com/items?itemName=blaugold.melos-code diff --git a/docs/index.mdx b/docs/index.mdx index b903b4227..52fc60d2a 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -2,13 +2,26 @@ description: A tool for managing Dart projects with multiple packages. --- -Melos +Melos ## About -Melos is a [CLI](https://en.wikipedia.org/wiki/Command-line_interface) tool used to help manage Dart projects with multiple packages (also known as mono-repos). It is currently still in active development however is in use on projects such as [FlutterFire](https://github.com/FirebaseExtended/flutterfire). +Melos is a [CLI](https://en.wikipedia.org/wiki/Command-line_interface) tool used +to help manage Dart projects with multiple packages (also known as mono-repos). +It is in active development and is in use on projects such as +[FlutterFire](https://github.com/firebase/flutterfire). -Splitting up large code bases into separate independently versioned packages is extremely useful for code sharing. However, making changes across many repositories is messy and difficult to track, and testing across repositories gets complicated. Melos helps solve these issues by allowing multiple packages to work together within one repository, whilst being totally independent of each other. Features include: +Splitting up large code bases into separate independently versioned packages is +extremely useful for code sharing. However, making changes across many +repositories is messy and difficult to track, and testing across repositories +gets complicated. Melos helps solve these issues by allowing multiple packages +to work together within one repository, whilst being totally independent of each +other. Features include: - Automatic versioning & changelog generation. - Automated publishing of packages to pub.dev. @@ -16,7 +29,8 @@ Splitting up large code bases into separate independently versioned packages is - Executing simultaneous commands across packages. - Listing of local packages & their dependencies. -Melos also works great on CI/CD environments to help automate complex tasks and challenges. +Melos also works great on CI/CD environments to help automate complex tasks and +challenges. ## Projects using Melos @@ -41,10 +55,28 @@ The following projects are using Melos: - [ferraridamiano/ConverterNOW](https://github.com/ferraridamiano/ConverterNOW) - [rrifafauzikomara/youtube_video](https://github.com/rrifafauzikomara/youtube_video) -> Submit a PR if you'd like to add your project to the list. -> Update the -> [docs](https://github.com/invertase/melos/edit/main/docs/index.mdx). + + +Submit a PR if you'd like to add your project to the list. Update the +[README.md](https://github.com/invertase/melos/edit/main/packages/melos/README.md) +and the [docs](https://github.com/invertase/melos/edit/main/docs/index.mdx). + +You can also add a [README badge](/#README-badge) to your projects README to let +others know about Melos 💙. + + + +## README Badge + +Using Melos? Add a README badge to show it off: + +[![melos](https://img.shields.io/badge/maintained%20with-melos-f700ff.svg?style=flat-square)](https://github.com/invertase/melos) + +```markdown +[![melos](https://img.shields.io/badge/maintained%20with-melos-f700ff.svg?style=flat-square)](https://github.com/invertase/melos) +``` ## License -See [LICENSE](https://github.com/invertase/melos/blob/main/LICENSE) for more information. +See [LICENSE](https://github.com/invertase/melos/blob/main/LICENSE) for more +information. diff --git a/packages/melos/README.md b/packages/melos/README.md index a0f9ae8ef..d9a996991 100644 --- a/packages/melos/README.md +++ b/packages/melos/README.md @@ -1,6 +1,21 @@

+ Melos

- A tool for managing Dart projects with multiple packages. + + A tool for managing Dart projects with multiple packages, inspired by Lerna. +

+ +

+ Melos + docs.page + + Chat on Discord + +

+ +

+ Documentation • + License

--- @@ -19,9 +34,7 @@ bases into multi-package repositories (sometimes called **Melos is a tool that optimizes the workflow around managing multi-package repositories with git and Pub.** ---- - -### What does a Melos workspace look like? +## What does a Melos workspace look like? A default file structure looks something like this: @@ -38,9 +51,7 @@ my-melos-repo/ The location of your packages can be configured via the `melos.yaml` configuration file if the default is unsuitable. ---- - -### What can Melos do? +## What can Melos do? - 🔗 Link local packages in your workspace together without adding dependency overrides. @@ -51,12 +62,12 @@ configuration file if the default is unsuitable. workspace can just run `melos run` to be prompted to select a script from a list with descriptions of each script. - Scripts can even - [prompt to select a package](https://github.com/invertase/melos/pull/34) to - run against with pre-defined filters. + [prompt to select a package](https://melos.invertase.dev/configuration/scripts#packagefilters) + to run against with pre-defined filters. - ⚡ Execute commands across your packages easily with - `melos exec -- command here` with additional concurrency and fail-fast + `melos exec -- ` with additional concurrency and fail-fast options. - - [Environment variables](https://github.com/invertase/melos/issues/3) + - [Environment variables](https://melos.invertase.dev/environment-variables) containing various information about the current package and the workspace are available in each execution. - Can be combined with all package filters. @@ -92,13 +103,16 @@ configuration file if the default is unsuitable. - `--no-depends-on=` - Include only packages that _don't_ depend on a specific package. - ♨️ Advanced support for IntelliJ IDEs with automatic creation of - [run configurations for workspace defined scripts and more](https://github.com/invertase/melos/issues/9) + [run configurations for workspace defined scripts and more](https://melos.invertase.dev/ide-support) on workspace bootstrap. - Integration with VS Code through an [extension][melos-code]. ---- +## Getting Started + +Go to the [Getting Started](https://melos.invertase.dev/getting-started) page of +the [documentation](https://docs.page/invertase/melos) to start using Melos. -### Who is using Melos? +## Who is using Melos? The following projects are using Melos: @@ -124,33 +138,21 @@ The following projects are using Melos: > Submit a PR if you'd like to add your project to the list. Update the > [README.md](https://github.com/invertase/melos/edit/main/packages/melos/README.md) > and the [docs](https://github.com/invertase/melos/edit/main/docs/index.mdx). -> You can also add a [readme badge](#readme-badge) to your projects readme to +> +> You can also add a [README badge](#readme-badge) to your projects README to > let others know about Melos 💙. ---- - -## Getting Started - -Go to the [Getting Started](https://melos.invertase.dev/getting-started) page of -the [documentation](https://docs.page/invertase/melos) to start using Melos. - ---- - -### Documentation +## Documentation Documentation is available at [https://melos.invertase.dev](https://melos.invertase.dev). ---- - -### Migrations +## Migrations When migrating between major versions of Melos, please read the [migration guide](https://melos.invertase.dev/guides/migrations). ---- - -### Commands +## Commands Full commands list and args can be viewed by running `melos --help`. @@ -178,14 +180,15 @@ Available commands: Run "melos help " for more information about a command. ``` ---- +## How to Contribute + +To start making contributions please refer to +[`CONTRIBUTING.md`](./CONTRIBUTING.md). ## Lerna This project is heavily inspired by [Lerna](https://lerna.js.org/). ---- - ## README Badge Using Melos? Add a README badge to show it off: @@ -196,25 +199,23 @@ Using Melos? Add a README badge to show it off: [![melos](https://img.shields.io/badge/maintained%20with-melos-f700ff.svg?style=flat-square)](https://github.com/invertase/melos) ``` ---- - ## License - See [LICENSE](/LICENSE) --- -

- -

-   Built and maintained with 💛 by Invertase. +

+ + + +

+ Built and maintained with 💛 by Invertase.

-

+

  Follow on Twitter

---- - [melos-code]: https://marketplace.visualstudio.com/items?itemName=blaugold.melos-code