Rebasing the Migration Branch on Latest Master [ARCHIVED]

NOTE: This page describes deprecated processes. It is maintained in case we have a future project that needs similar steps.

Since we cannot freeze release of new documentation while working on the Redocly migration, our approach is to maintain two branches:

• The master branch continues to work on Dactyl until we are ready for a final "code freeze" (<2 weeks) to switch over.
• The redocly-migration branch contains Redocly-specific work and is periodically re-based on master.

This page describes how to do the rebase.

Steps

1. Pull the latest master and redocly-migration branches to your local Git instance.

git switch master
git pull
git switch redocly-migration
git pull

2. On the redocly-migration branch, start an interactive rebase

git rebase -i

3. In the interactive "to-do" list, there are several things you want to do:

   • Drop commits tagged with [DROP], by changing pick to drop (or d). In the following cases, you should also add a break line after that so you can manually re-create the commit on the latest master:
     • The commit to move assets/ to content/static/. If no assets have changed in the master branch since the last rebase, you can skip this and leave the previous [DROP] commit in-place (leave it as pick).
     • The [DROP] Migrate content syntax commit. This is the main result of running the script.
   • In some other cases, you can drop a commit with no further action. Examples of these include commits that applied some migration script updates, temporary fixes to content that were also rolled into the migration script, or temporary fixes that are no longer necessary due to updates to Redocly. These commits should be tagged with [DROP] but we might miss one or two.
   • Move and squash commits tagged with [FOLD], typically ones that modify the migration script. Keep them in the same order relative to one another, change pick to s (for squash), and move them to be after Create script to migrate links and content syntax and before the [DROP] Migrate content syntax.
   • Optionally, you can fix up other commits, like using r (reword) to correct a commit message that isn't quite right.

   Tip: If you're using vim for editing git's to-do list, use dd to cut and p to paste lines. It may also be useful to copy-paste the entire to-do list to a text file in another window to help you orient yourself while you do the rest of the rebase.

   When you've got the to-do list how you want it, save and exit. This starts the rebase.

4. Git may interrupt the rebase for a merge conflict. If you aren't sure, use git status and your text file of the entire to-do list to orient yourself to what needs doing.

   Merge conflicts can occur because a commit in the redocly-migration branch touched on a line that either (a) got updated in master since the last rebase, or (b) was handled differently by the migration script compared with last time. You need to actually look at each individual conflict and decide how to resolve it: sometimes one version or the other is correct, or sometimes you need a combination of the two. Use git add to mark resolution of the files as you go, and do git rebase --continue when you've finished resolving merge conflicts.

5. Git also pauses the rebase at the explicit break points you've set. When this comes up, re-create the migration commit as needed.

   For the "Migrate content syntax" commit, run tool/migrate.sh, which may take a few minutes to finish while being mostly quiet. Any messages it outputs to the console are probably worth paying attention to, although you may not need to take immediate action. When it's done, git add content/ tool/ and git commit with a commit message such as the following:

   [DROP] Migrate content syntax (2024-01-22 v4)
   
   The changes in this commit were auto-generated by doing:
   
   tool/migrate.sh
   
   When rebasing the migration branch on the latest master, this commit
   should be dropped and re-created (probably using the same command).
   

   (Rome's note: I've taken to adding the date, and if it takes me more than one try to get it right, a version number, to the top of the commit message.)

   If you encounter problems with the migration script(s), you can use commands like git checkout -- content or git reset --hard to reset it, although you might separately need to remove untracked files and folders like rm content/@i18n/ja/_snippets/. Then you can edit the scripts or other files and re-run them. If things work right, you should commit the changes to the scripts first (as [FOLD] commits for next time).

   For the static files migration, the commands to re-create the commit are git mv assets content/static and git mv img content/img and the commit message can be something like the following:

   [DROP] Move static files to content dir
   
   The changes in this commit were generated by doing:
   
   git mv assets content/static
   git mv img/ content/img
   
   When rebasing the migration branch on the latest master, this commit
   should be dropped and re-created (possibly using the same command).
   

   (Edit the message accordingly if you do things differently, like if this is after re-levelization and you're moving assets to static at the top level instead.)

   After you've re-created the commit, use git rebase --continue to resume the rebase.

6. Continue fixing merge conflicts as they come up.

7. When you are done, you should have a rebased redocly-migration branch that has many different commits than the one in the upstream repo. Check that your local branch works OK, for example by doing these commands:

   npm i
   npm run start

   Test out the site on the local dev server and make sure things are reasonable. If something's wrong, you may want to add more commits to fix it, or do a git rebase --abort and start over (which may be your best option if the migration script needed fixes).

8. If it seems fine, force-push the branch to GitHub and notify collaborators that you've done so.

   git push -f

   This may also be a good time to remind people of the instructions for rebasing their feature branches.