diff --git a/docs/README.md b/docs/README.md index 81c02397664..07d284c743d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -22,7 +22,6 @@ Hi! Welcome to the contributor documentation for the `core` monorepo. - [Building packages](./processes/building.md) - [Adding new packages to the monorepo](./processes/adding-new-packages.md) - [Migrating external packages to the monorepo](./processes/package-migration-process-guide.md) - - [Migrating tags](./processes/migrate-tags.md) ## Code guidelines diff --git a/docs/processes/migrate-tags.md b/docs/processes/migrate-tags.md deleted file mode 100644 index 58a7d836124..00000000000 --- a/docs/processes/migrate-tags.md +++ /dev/null @@ -1,169 +0,0 @@ -# Migrating tags from other repos - -When migrating libraries into the core monorepo, the original git history is transferred using the `git-filter-repo` tool (instructions [here](./package-migration-process-guide.md)), but tags attached to release commits are excluded from the process. This is because the tag names (`v[major].[minor].[patch]`) first need to be adjusted to conform to the scheme used by the core repo (`@metamask/@[major].[minor].[patch]`). - -The `./scripts/migrate-tags.sh` script automates the process of enumerating the tags and associated release commit messages in the original repo, searching the migrated git history in the core repo's `merged-packages/` directory for each commit message, creating tags with correctly-formatted names and attaching them to the found release commits, and pushing those tags to the core repo. - -## A. Preparations - -- The migration target package must be inside of the `merged-packages/` directory with its git history fully migrated. -- The script must be run from the root directory of the core repo. -- The `/tmp/` directory used during the git history migration process should still be accessible. If not, perform steps 1-5 of [these instructions](https://github.com/MetaMask/core/issues/1079#issuecomment-1700126302) before proceeding. -- If the script isn't executable, run `chmod +x ./scripts/migrate-tags.sh`. -- By default, this script will run in "dry mode", printing out all pairs of release commit hashes and prefixed tag names, but not modifying the local or remote repo in any way. To override this and actually create/push tags, run the script with a `--no-dry-run` flag appended at the end. - -## B. Options - -- `` (required). - - Only supply the package directory name. Exclude the `@metamask/` namespace. -- `-r`, `--remote` (optional): the git remote repo where the tags will be pushed. - - Default if omitted: "test". -- `-v`, `--version-before-package-rename` (optional) - - Default if omitted: `0.0.0`. - - **If `-v` is not passed, all tag names will be prepended with the `@metamask/` namespace.** -- `-t`, `--tag-prefix-before-package-rename` (optional) - - Default if omitted: `` supplied in the first argument. -- `-d`, `--tmp-dir` (optional) - - Default if omitted: `/tmp` - - Specifies the temporary directory where `git-filter-repo` was applied to a clone of the original repo. -- `-p`, `--sed-pattern` (optional): sed pattern for extracting version numbers from the original repo's tag names. - - Default if omitted: `'s/^v//'` - - If the original tag names follow a different naming scheme than `v[major].[minor].[patch]`, adjust this setting. -- `--no-dry-run` (optional): - - Default if omitted: `false`. - - If not specified, the script will run in "dry run" mode. The script will print out all pairs of release commit hashes and prefixed tag names, but without modifying the local or remote repo in any way. - - **This flag MUST be enabled for tags to be created and pushed.** - - Make sure to specify the correct remote repo where the tags will be pushed by using the `-r` flag. - -## C. Usage - -### 1. General Case (package never renamed) - -- For most cases, you will only need to specify the `` as the first argument. - -```shell -> ./scripts/migrate-tags.sh eth-json-rpc-provider -``` - -```output -328a43ed @metamask/eth-json-rpc-provider@1.0.0 -06c41f6a @metamask/eth-json-rpc-provider@1.0.1 -de124c41 @metamask/eth-json-rpc-provider@2.0.0 -0aa45a9a @metamask/eth-json-rpc-provider@2.1.0 -d3a9f01c @metamask/eth-json-rpc-provider@2.2.0 -``` - -### 2. Renamed Package - -- If the migration target package has been renamed, specify the `-v`, `--version-before-package-rename` option. - -```shell -> ./scripts/migrate-tags.sh json-rpc-engine -v 6.1.0 -``` - -```output -67c7fee5 @metamask/json-rpc-engine@7.2.0 -23aa8d9e @metamask/json-rpc-engine@7.1.1 -76394323 @metamask/json-rpc-engine@7.1.0 -22ff65e0 @metamask/json-rpc-engine@7.0.0 -c753c16c @metamask/json-rpc-engine@7.0.0 -670d8dd7 json-rpc-engine@6.1.0 -9646dc26 json-rpc-engine@6.0.0 -... -``` - -- The above output shows two `7.0.0` entries. If any duplicate release commits are found, the script will create and push tags only on the most recent commit. -- The user has the option to supply a custom regex pattern under `-p` to narrow down the search results for the release commits. - -### 3. Package will be Renamed on the first Post-Migration Release - -- If the migration target package will be renamed after the migration, **specify the latest release version** in `-v`. - -```shell -> ./scripts/migrate-tags.sh json-rpc-middleware-stream -v 5.0.1 -``` - -```output -38c007a3 json-rpc-middleware-stream@5.0.1 -c34b1704 json-rpc-middleware-stream@5.0.0 -8c6b70e5 json-rpc-middleware-stream@4.2.3 -f7290013 json-rpc-middleware-stream@4.2.2 -e08455ca json-rpc-middleware-stream@4.2.1 -d90fe43d json-rpc-middleware-stream@4.2.0 -... -``` - -### 4. Non-Dry Mode - -- To override dry run mode and actually create/push tags, run the script with a `--no-dry-run` flag at the end. -- Make sure to specify the correct remote repo where the tags will be pushed by using the `-r` flag. - -```shell -> ./scripts/migrate-tags.sh json-rpc-middleware-stream -v 5.0.1 -r origin --no-dry-run -``` - -```output -Total 0 (delta 0), reused 0 (delta 0), pack-reused 0 -To https://github.com/[USERNAME]/[FORKNAME] - * [new tag] json-rpc-middleware-stream@5.0.1 -> json-rpc-middleware-stream@5.0.1 -Total 0 (delta 0), reused 0 (delta 0), pack-reused 0 -To https://github.com/[USERNAME]/[FORKNAME] - * [new tag] json-rpc-middleware-stream@5.0.0 -> json-rpc-middleware-stream@5.0.0 -Total 0 (delta 0), reused 0 (delta 0), pack-reused 0 - -... - -To https://github.com/[USERNAME]/[FORKNAME] - * [new tag] json-rpc-middleware-stream@2.0.0 -> json-rpc-middleware-stream@2.0.0 -Total 0 (delta 0), reused 0 (delta 0), pack-reused 0 -To https://github.com/[USERNAME]/[FORKNAME] - * [new tag] json-rpc-middleware-stream@1.0.1 -> json-rpc-middleware-stream@1.0.1 -``` - -## D. Verify - -- Check whether the tags have correctly been pushed to the remote repo. - -```shell -> git ls-remote --tags origin | grep 'json-rpc-engine' -``` - -```output -22ff65e0f76710188b527bd5d3f81dd2103c5514 refs/tags/@metamask/json-rpc-engine@7.0.0 -7639432339e60767a8239d681911375833bc3839 refs/tags/@metamask/json-rpc-engine@7.1.0 -23aa8d9e59d9275c0725cb0264057e082034dae9 refs/tags/@metamask/json-rpc-engine@7.1.1 -67c7fee5141f6c0bb2f459c1cb3062c02bbf6a15 refs/tags/@metamask/json-rpc-engine@7.2.0 -304f6efa4d1be2460c9d0bec48224cefcf7fd208 refs/tags/json-rpc-engine@1.0.0 -4909d7fd95a555a7ae18cb1f9840db4fe1f3c85d refs/tags/json-rpc-engine@2.0.0 -93e2b7224f7370468466e2e5e29a2c10da016b11 refs/tags/json-rpc-engine@2.1.0 -286c2716a7b856b95f74d64edd9e653728dd031c refs/tags/json-rpc-engine@2.2.0 -... -``` - -## E. Troubleshooting - -> [!WARNING] -> DO NOT run this script on the core repo until the results have been tested on a fork. - -The following commands should NOT be run on the core repo unless something has gone very wrong. - -### 1. Delete remote tags - -**WARNING**: Proceed with EXTREME CAUTION - -```shell -> git ls-remote --tags | grep '' | cut -f2 | sed 's|refs/tags/||g' | xargs git push --delete -``` - -- ALWAYS create a backup clone repo in advance and delete local tags AFTER remote tags. -- If something goes wrong, try `git push ` to push the local tags to remote. -- If the local tags have been deleted, push the unaltered tags in the backup clone repo to remote. -- If this fails, ask a teammate who has the correct tags on local to push them to remote. - -### 2. Delete local tags - -```shell -> git tag | grep '' | xargs git tag --delete -``` - -- If anything goes wrong, run `git pull --all` and the tags in the remote repo will be restored to local. diff --git a/docs/processes/package-migration-process-guide.md b/docs/processes/package-migration-process-guide.md index 872900d980c..31b4d676a02 100644 --- a/docs/processes/package-migration-process-guide.md +++ b/docs/processes/package-migration-process-guide.md @@ -65,6 +65,17 @@ This document outlines the process for migrating a MetaMask library into the cor - [Example PR](https://github.com/MetaMask/core/pull/1872) +#### After PR#6 lands: tag the latest source-repo release in core + +`action-publish-release` checks GitHub for an existing tag before publishing. If the latest version published from the source repo has no matching tag in `core`, the action will try to release that version again and fail. Create a tag in `core` for the last source-repo release and push it to `origin`: + +```shell +git tag -a @metamask/@ +git push origin @metamask/@ +``` + +Find the release commit SHA with `git log --oneline merged-packages/` and match the release commit message from the source repo. + ### **[PR#7]** 2. Reset the CHANGELOG, adding a link to the old repository - Create a fresh CHANGELOG file with no releases diff --git a/scripts/migrate-tags.sh b/scripts/migrate-tags.sh deleted file mode 100755 index 772aeb74110..00000000000 --- a/scripts/migrate-tags.sh +++ /dev/null @@ -1,165 +0,0 @@ -#!/usr/bin/env bash - -source "$PWD/scripts/semver.sh" - -remote='test' -version_before_package_rename='0.0.0' -tag_prefix_before_package_rename="$1" -tmp_dir='/tmp' -sed_pattern='s/^v//' -dry_run=true - -print-usage() { - cat <&2 - elif [[ $dry_run == true ]]; then - echo "$commit"$'\t'"$tag_name"$'\t'"$message" - else - echo "Creating tag '$tag_name'..." - git tag "$tag_name" "$commit" - git push "$remote" "$tag_name" - fi - done <<<"$(get-commit-tagname-pairs)" -} - -main