Document how to vendor a repo

changelog.d/+document-how-to-vendor-a-repo.added.md

@@ -0,0 +1 @@
+Added docs for how to vendor a repo (copy one repo into another, preserving history).

docs/development/howtos/vendor-a-repo.rst

@@ -0,0 +1,204 @@
+====================
+How to vendor a repo
+====================
+
+By "vendoring a repo" we mean to include the source code of a repo into an
+existing repo. Following this how to will give you one repo with an extra root.
+
+The TARGET repo is the the repo we want to end up with while the ORIGIN
+repo is the one we want to merge in (our terms). In this case, we wish to merge
+the "main" branch of ORIGIN into the "master" branch of TARGET. (It is easier
+to keep track if the branches have different names.)
+
+This how to assumes that ORIGIN and TARGET has no shared history, as is
+the case if ORIGIN is a standalone library or django app.
+
+Prep the ORIGIN repo
+--------------------
+
+1. Be placed somewhere there is no git repo
+2. Clone the ORIGIN repo locally::
+
+        git clone ORIGIN-clone path/to/ORIGIN
+
+3. cd into ORIGIN-clone
+4. Make sure you are on "main" branch of ORIGIN-clone
+5. Move every single file found by ``.gitignore`` in ORIGIN to a new directory that
+   does not exist on TARGET, we'll standardize on ``merge/`` here::
+
+        mkdir merge
+        git mv -k * merge/
+
+   Without the "-k"-flag, ``git mv`` would error out with ``fatal: can not move
+   directory into itself, source=merge, destination=merge/merge`` and refuse to
+   do anything.
+
+   Finally move the hidden files (filenames that start with ".")::
+
+        git mv -k .* merge/
+
+   Everything should now be in ``merge/`` except for the magic directory
+   ``.git/``, any files hidden by ``.gitignore``, and any untracked files. This
+   is as it should be.
+
+6. Commit::
+
+        git commit -m 'Move repo contents into subdirectory'
+
+7. Add the TARGET repo as a remote to the ORIGIN-clone::
+
+        git remote add TARGET path/to/TARGET
+
+8. Fetch the TARGET repo into the ORIGIN-clone repo::
+
+        git fetch TARGET
+
+9. Merge ORIGIN-clone's "main" into feceiving's "master"::
+
+        git merge --allow-unrelated-histories TARGET/master
+
+10. Push the master/main of the ORIGIN-clone to a temporary branch on TARGET::
+
+        git push -u TARGET merge-ORIGIN
+
+You're finished with the ORIGIN-clone. You may remove it if you like.
+
+Fix up the TARGET repo
+----------------------
+
+1. Switch to a local clone of the TARGET repo
+2. Checkout and pull the temporary branch::
+
+        git checkout -b merge-ORIGIN
+        git pull
+3. You can either merge to master now (recommended) or start a new branch off
+   merge-ORIGIN for the fixing-up. The goal is to have two different branches:
+   one that is a clean copy of ORIGIN's history, one that does all the fixing.
+   This makes the latter easy to review and safer to do in general.
+4. Whether you merged to master or not, start a new branch for the fixing::
+
+        git switch -c move-ORIGIN-files-to-correct-location
+
+5. Do all the moving. Remember that ORIGIN's code might have additional stuff
+   in it's ``.gitignore`` and other files (inside ``merge/``) that needs
+   to be *added* to the corresponding files of TARGET. Make one commit for
+   all files that can be moved without changes and then commit each time you
+   need to merge in new stuff. If you need to update import paths or file paths
+   in either, they also get a commit each, per path. So: if ORIGIN's module
+   name is "my_fine_app" and it will be moved to TARGET's file hierarchy as
+   "src/argus/my_fine_app" and module hierarchy as "argus.my_fine_app", make
+   one commit for all the file path changes and another for all the "import"
+   changes.
+6. Push move-ORIGIN-files-to-correct-location upstream so others can have a look::
+
+        git push -u move-ORIGIN-files-to-correct-location
+
+7. When done and tests are green, merge/rebase/squash to master (you can do
+   this via github).
+
+Done!
+
+If ORIGIN is to cease to exist as a repo, move open issues to TARGET's repo.
+
+Moving issues
+-------------
+
+Github can move issues between Github repos just fine. There's a link to move
+issues in the right-hand menu on each issue page. If the TARGET repo has the
+labels of the ORIGIN repo, the labels will copy over just fine too.
+
+
+Move other branches from ORIGIN to TARGET
+=========================================
+
+Move PR
+-------
+
+If you want to move a PR to the argus-server repo (TARGET) you first need to
+move the branch, then start a new PR with the same name at argus-server, then
+link back to any discussion in this repo from the new PR. Now you can close the
+PR in this repo.
+
+Prep code in ORIGIN
+-------------------
+
+In your local copy of ORIGIN (or a new clone) make a branch off main called rename::
+
+        git switch -c rename
+
+Move the code of main (just the code) to the paths that are correct for
+TARGET. Feel free to also update import paths and template paths in this
+code. Commit the changes to the ``rename`` branch.
+
+If the code is going into a new subdirectory, make sure the parent directory is
+empty. If necessary ``git rm`` the ``__init__.py`` file or any others.
+
+Setup the remote in the ORIGIN repo
+-----------------------------------
+
+1. Add the TARGET repo as a remote::
+
+        git remote add TARGET url/to/TARGET
+
+2. Fetch the branches on argus::
+
+        git fetch TARGET
+
+3. Checkout master::
+
+        git switch master
+
+Move the actual branch
+----------------------
+
+First move your branch onto the ``rename`` branch.
+
+Do ``git mv old new`` or ``git rebase rename mybranch`` or use a graphical
+client to cherry-pick one by one onto main, or copy the files to the correct
+place and add+commit them as new. It is enough to just move the files.
+Correcting import paths and file include paths can be done *after* the move, in
+the new repo, with a new commit.
+
+This way, you can deal with file renaming conflicts once, and content change
+conflicts once.
+
+Now you're ready for the move.
+
+1. Make a temporary branch name for the branch you want to move, at its head::
+
+        git switch mybranch
+        git switch -c fvgyhj
+
+2. If it's only a single commit you can cherry-pick it. Move the real name to
+   the master then cherry-pick::
+
+        git branch -f mybranch master
+        git switch mybranch
+        git cherry-pick fvgyhj
+
+   If not, a rebase can do it for you. If you didn't do step 1 correctly there
+   will be more conflicts than necessary!
+
+   How to rebase (assumes ``mybranch`` is rebased on ``rename``)::
+
+        git rebase --onto master rename mybranch
+
+   You can now remove the temporary branch::
+
+        git branch -d fvgyhj
+
+3. Push the branch to the new remote::
+
+        git switch mybranch
+        git push TARGET
+
+Make a new PR
+-------------
+
+1. Make the PR in TARGET's repo and pull the branch in your local copy of
+   that repo.
+
+2. Do any internal changes to the actual code in the new repo if you didn't do
+   that as a part of the branch prep.
+
+Done!