API migration guide. (#1133)

An *API Migration Guide* section is added to the porting guide.

A symbolic link is created as `mmtk-core/API-MIGRATION.md` which can be
easily discovered from the root of the repository.

---------

Co-authored-by: Yi Lin <[email protected]>

.github/scripts/ci-doc.sh

@@ -24,5 +24,5 @@ cargo build
 
 # Install mdbook using the stable toolchain and the default target
 unset CARGO_BUILD_TARGET
-cargo +stable install mdbook
+cargo +stable install mdbook mdbook-admonish mdbook-hide
 mdbook build $project_root/docs/userguide

.github/workflows/api-check.yml

@@ -38,3 +38,24 @@ jobs:
         run: cargo install cargo-public-api
       - name: API Diff
         run: cargo public-api diff origin/${GITHUB_BASE_REF}..${{ github.event.pull_request.head.sha }} --deny=all
+
+  check-api-migration-update:
+    needs: check-public-api-changes
+    runs-on: ubuntu-latest
+    if: ${{ always() && needs.check-public-api-changes.result == 'failure'}}
+    env:
+      MIGRATION_GUIDE_PATH: 'docs/userguide/src/migration/**'
+    steps:
+      # Check if migration guide is updated.
+      - name: Get the update status for the migration guide.
+        uses: tj-actions/changed-files@v44
+        id: migration-guide-status
+        with:
+          files: ${{ env.MIGRATION_GUIDE_PATH }}
+      # If the api check failed but the migration is not updated, we fail here
+      - name: Report if the migration guide is not updated.
+        if: ${{ steps.migration-guide-status.outputs.any_changed == 'false' }}
+        uses: actions/github-script@v7
+        with:
+          script: |
+            core.setFailed('Public API is changed, but the migration guide (${{ env.MIGRATION_GUIDE_PATH }}) is not updated. If the bindings need to be updated for the API change, the migration guide needs to be updated as well.')

.github/workflows/merge-check.yml

@@ -19,6 +19,7 @@ env:
       "ready-to-merge",
       "check-broken-links-in-docs",
       "check-public-api-changes",
+      "check-api-migration-update",
       "minimal-tests-core/x86_64-unknown-linux-gnu/stable",
       "minimal-tests-core/i686-unknown-linux-gnu/stable",
       "minimal-tests-core/x86_64-apple-darwin/stable",

.github/workflows/rustdoc.yml

@@ -20,6 +20,9 @@ jobs:
         run: |
           sed -i 's/^version = "[0-9]\+.[0-9]\+.[0-9]\+/&-'${GITHUB_SHA}'/' Cargo.toml
       - name: Generate rustdoc
+        env:
+          # Override preprocessor.hide.hide in book.toml to hide some chapters.
+          MDBOOK_preprocessor__hide__hide: "true"
         run: ./.github/scripts/ci-doc.sh
       - name: Copy docs
         # docs.mmtk.io is the root for github pages.

README.md

@@ -89,6 +89,7 @@ To integrate MMTk with your language implementation, you need to provide an impl
 you can optionally call MMTk's API for your needs.
 
 For more information, you can refer to our [porting guide](https://docs.mmtk.io/portingguide/prefix.html) for VM implementors.
+We maintain a [migration guide](https://docs.mmtk.io/migration/prefix.html) to help VM implementors to migrate MMTk to newer versions.
 
 ### Implement your GC
 

docs/userguide/assets/css/api-migration-details.css

@@ -0,0 +1,10 @@
+/* Make the "show details" text on the third level smaller and keep the same indentation as the folded sub-list. */
+#api-migration-detail-body details.api-migration-level3-detail > summary {
+    padding-left: 2em;
+    font-size: small;
+}
+
+/* Hide the "show details" when open, to keep the text less cluttered. */
+#api-migration-detail-body details[open] > summary {
+    display: none;
+}