docs: add notes about importing existing projects into depot
Change-Id: Idc8572ae68eb9513c6c63642737ce8fd004ee67e Reviewed-on: https://cl.tvl.fyi/c/depot/+/12325 Reviewed-by: azahi <azat@bahawi.net> Tested-by: BuildkiteCI Autosubmit: tazjin <tazjin@tvl.su> Reviewed-by: benjaminedwardwebb <benjaminedwardwebb@gmail.com>
This commit is contained in:
parent
3e4b9e56a5
commit
8edfb085f5
1 changed files with 91 additions and 0 deletions
91
docs/importing-projects.md
Normal file
91
docs/importing-projects.md
Normal file
|
@ -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).
|
Loading…
Reference in a new issue