From 8edfb085f53e75a0183d7adca13704ba72f383d0 Mon Sep 17 00:00:00 2001 From: Vincent Ambo Date: Sat, 24 Aug 2024 12:25:57 +0300 Subject: docs: add notes about importing existing projects into depot Change-Id: Idc8572ae68eb9513c6c63642737ce8fd004ee67e Reviewed-on: https://cl.tvl.fyi/c/depot/+/12325 Reviewed-by: azahi Tested-by: BuildkiteCI Autosubmit: tazjin Reviewed-by: benjaminedwardwebb --- docs/importing-projects.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/importing-projects.md (limited to 'docs') diff --git a/docs/importing-projects.md b/docs/importing-projects.md new file mode 100644 index 000000000000..c68c8b1906ae --- /dev/null +++ b/docs/importing-projects.md @@ -0,0 +1,91 @@ +Importing projects into depot +============================= + +Before importing an existing `git`-based project into depot, a few questions +need to be answered: + + +* Is the project licensed under a free software license, or public domain? +* Do you need to import existing history? +* Do you need to export new history with hashes that continue on from the old + history? (e.g. importing an existing repository, and exporting from depot to + the old upstream) + +Think about this and then pick an approach below: + +## Import with no history (just commit) + +Simply copy the files to where you want them to be in depot, and commit. Nothing +else to do! + +## Import without continuous history (subtree merge) + +This import approach lets you drop an existing project into depot, keep its +existing history, but not retain the ability to continue external history. + +This means that if you, for example, import a project from a different git host +using this method, and then continue to commit to it inside of depot, you will +not be able to export a history consistent with your previous hashes using +`josh`. + +Commit hashes before the import will exist in depot and be valid. + +Still, this approach might be viable if a project "moves into" depot, or has +nothing depending on it externally. + +1. Pick a location in depot where you want your project to be (`$loc` from now on). +2. Fetch your project into the same git store as your depot clone (e.g. by + adding it as an upstream and fetching it). +3. Pick the commit you want to merge (`$commit` from now on). +4. Run `git subtree add --prefix=$loc $commit`, which will create the correct + merge commit. +5. Ensure Gerrit [knows about your commit](#preparing-merges-in-gerrit) for the + parent that is being merged. +6. Modify the merge commit's message to start with `subtree($project_name):`. + Gerrit **will not** allow merge commits that do not follow this format. +7. Push your subtree commit for review as normal. + +## Import with continuous history + +This approach imports the history using `josh`, which means that external +history before/after the import is consistent (you can continue committing in +`depot`, export the history back out, and from an external perspective nothing +changes). + +This is what we did with repositories like `nix-1p` and `nixery`. + +Note: Inside of depot, the pre-import commit hashes will **not make sense**. +`josh` will rewrite them in such a way that exporting the project will yield the +same hashes, but this rewriting changes the hashes of your commits inside of +depot. + +1. Pick a location in depot where you want your project to be (`$loc`). +2. Fetch your project into the same git store as your depot clone (e.g. by + adding it as an upstream and fetching it). +3. Check out the commit you want to merge into depot. +4. Run `josh-filter ":prefix=$loc"`, and take note of the `FILTERED_HEAD` ref + that it produces (`$filtered` from now on). +5. Ensure Gerrit [knows about the filtered commit](#preparing-merges-in-gerrit). +6. Merge the filtered commit into depot using a standard merge, but make sure to + add the `--allow-unrelated-histories` flag. Your commit message **must** + start with `subtree($project_name):`, otherwise Gerrit will not let you push + a merge. +7. Push the merge commit for review as usual. + +------------------------------------------------------ + +## Preparing merges in Gerrit + +When pushing a merge to Gerrit, it needs to know about all ancestors of the +merge, otherwise it will try to interpret commits as new CLs and reject them for +not having a change ID (or create a huge number of CLs, if they do have one). + +To prevent this, we have a special git ref called `subtree-staging` which you +can push external trees to. + +Access to `subtree-staging` has to be granted by a TVL admin, so ping tazjin, +lukegb, flokli, sterni and so on before proceeding. + +1. Determine the commit you want to merge (`$commit`). +2. Run `git push -f $commit origin/subtree-staging` (or replace `origin` with + whatever the TVL Gerrit remote is called in your clone). -- cgit 1.4.1