diff --git a/README.md b/README.md index 734f65f..a46945f 100644 --- a/README.md +++ b/README.md @@ -37,4 +37,4 @@ This guide houses the information needed to get started with and use institute r ## Acknowledgments -This work was supported by both the [Imageomics Institute](https://imageomics.org) and the [AI and Biodiversity Change (ABC) Global Center](http://abcresearchcenter.org). The Imageomics Institute is funded by the US National Science Foundation's Harnessing the Data Revolution (HDR) program under [Award #2118240](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2118240) (Imageomics: A New Frontier of Biological Information Powered by Knowledge-Guided Machine Learning). The ABC Global Climate Center is funded by the US National Science Foundation under [Award No. 2330423](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2330423&HistoricalAwards=false) and Natural Sciences and Engineering Research Council of Canada under [Award No. 585136](https://www.nserc-crsng.gc.ca/ase-oro/Details-Detailles_eng.asp?id=782440). This guide draws on research supported by the Social Sciences and Humanities Research Council. Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation, Natural Sciences and Engineering Research Council of Canada, or Social Sciences and Humanities Research Council. +This work was supported by both the [Imageomics Institute](https://imageomics.org) and the [AI and Biodiversity Change (ABC) Global Center](http://abcresearchcenter.org). The Imageomics Institute is funded by the US National Science Foundation's Harnessing the Data Revolution (HDR) program under [Award #2118240](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2118240) (Imageomics: A New Frontier of Biological Information Powered by Knowledge-Guided Machine Learning). The ABC Global Center is funded by the US National Science Foundation under [Award No. 2330423](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2330423&HistoricalAwards=false) and Natural Sciences and Engineering Research Council of Canada under [Award No. 585136](https://www.nserc-crsng.gc.ca/ase-oro/Details-Detailles_eng.asp?id=782440). This guide draws on research supported by the Social Sciences and Humanities Research Council. Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation, Natural Sciences and Engineering Research Council of Canada, or Social Sciences and Humanities Research Council. diff --git a/docs/wiki-guide/Git-Cherry-Pick-Guide.md b/docs/wiki-guide/Git-Cherry-Pick-Guide.md new file mode 100644 index 0000000..a702151 --- /dev/null +++ b/docs/wiki-guide/Git-Cherry-Pick-Guide.md @@ -0,0 +1,81 @@ +# Git Cherry-pick update for Downstream Repos + +`git cherry-pick` is a handy tool to directly apply specific commits from one branch or repo to another even when they don't share a git history—especially when you do not want to merge large change sets. This can be helpful when forking another repo or building off an evolving template, such as the [Collaborative Distributed Science Guide](https://github.com/Imageomics/Collaborative-distributed-science-guide). Below, we provide a step-by-step guide to updating repositories based on updating this repo from the template guide: + +!!! tip "Be Prepared!" + Before you start, you should know which commits are going to be pulled from the template repo. Collect their hashes in a separate text file; be sure to list them in chronological order, so they can be applied correctly. + +1. **Ensure the target repo is up-to-date.** +2. Create a new branch onto which to pull the changes: + + ```console + git checkout -b dev + ``` + +3. Check the remotes available for your repo: + + ```console + git remote -v + ``` + + !!! note + If you haven't added the template repo as a remote yet, you will only see the current repo options (`origin`): + + ```console + origin git@github.com:Imageomics/Imageomics-guide.git (fetch) + origin git@github.com:Imageomics/Imageomics-guide.git (push) + ``` + + In which case, run the following to add the template guide as an available remote under the title `upstream`: + + ```console + git remote add upstream git@github.com:Imageomics/Collaborative-distributed-science-guide.git + ``` + + After running `git remote -v`, you should then see + + ```console + origin git@github.com:Imageomics/Imageomics-guide.git (fetch) + origin git@github.com:Imageomics/Imageomics-guide.git (push) + upstream git@github.com:Imageomics/Collaborative-distributed-science-guide.git (fetch) + upstream git@github.com:Imageomics/Collaborative-distributed-science-guide.git (push) + ``` + +4. Run `git fetch upstream` to get the commits from the template repo (now recognized as `upstream`). +5. Run `git cherry-pick --edit `, this way, the URL pointing to the Collaborative Distributed Science Guide can be modified to function properly from the downstream repo. Ex: + + ```console + git cherry-pick --edit a3d2f5d621aaa5b9a543fabad3f813ceb45964d4 + ``` + + The next screen should provide the commit message for editing: + + ```console + Update GitHub Repo Archiving Guidance (#29) + + * Add section on automatically maintaining metadata on Zenodo + ... + ``` + + press ++i++, then, using arrow keys to navigate the console edit the message to the following: + + ```console + Update GitHub Repo Archiving Guidance + + Pull from Collab Guide [PR 29](https://github.com/Imageomics/Collaborative-distributed-science-guide/pull/29) + + * Add section on automatically maintaining metadata on Zenodo + ... + ``` + + The URL will render as "[Imageomics/Collaborative-distributed-science-guide#29](https://github.com/Imageomics/Collaborative-distributed-science-guide/pull/29)", with the functional hyperlink. Finally, select ++esc++ and type `:wq` to complete the commit message edit. + + !!! info "Conflicts Happen" + If you have a merge conflict, open the file, resolve the conflict, and then `git add` the file. From that point you should be able to run `git cherry-pick --continue` and it will provide the commit message from the upstream. Checking `git status` and `git log` at various points in this process will allow you to check on how these are progressing and see the addition of the upstream commits to your current repo's branch. + +6. Once you've collected all the upstream commits, run `git push --set-upstream origin dev` to add them to the current repo. +7. Open a pull request from the `dev` branch to add these upstream commits to `main`. Be sure to include a description of the commits, where they came from, and include links to PRs _from the upstream repo_. Auto-links generated by GitHub (based on `#`) will link to that number issue or PR in the current repo, not the upstream one. + +8. Rebase commit the PR. This allows for the changes pulled from upstream to be seamlessly integrated into the downstream repo. The commit hashes are not preserved across repositories, so there is no information to lose. + +See also [`git cherry-pick`](https://git-scm.com/docs/git-cherry-pick) for more info on available options. diff --git a/docs/wiki-guide/Two-Repo-Problem.md b/docs/wiki-guide/Two-Repo-Problem.md index 6468f89..6966578 100644 --- a/docs/wiki-guide/Two-Repo-Problem.md +++ b/docs/wiki-guide/Two-Repo-Problem.md @@ -250,10 +250,12 @@ This method is used when the same commits exist in both repos with different has This requires finding which commits are in the private repo but not in the public repo. !!! warning "Warning" - If the commits you cherry-pick have commits in common with different hashes this will result in merge conflicts and duplicated commits. + If the commits you cherry-pick have content in common under commits with different hashes this will result in merge conflicts or duplicated commits. Be sure to list all commits to cherry-pick in chronological order before you begin. After fetching your upstream branch you can cherry pick a range of commits to add like so: ``` git cherry-pick .. ``` + +See the [Git Cherry-Pick Guide](Git-Cherry-Pick-Guide.md) for more details and an example of the full process. diff --git a/mkdocs.yaml b/mkdocs.yaml index f48e60d..2c39936 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -104,6 +104,7 @@ nav: - "Projects Guide": wiki-guide/Guide-to-GitHub-Projects.md - "Branch Protections": wiki-guide/When-to-think-about-branch-protections.md - "Two Repo Problem": wiki-guide/Two-Repo-Problem.md + - "Git Cherry-Pick Guide": wiki-guide/Git-Cherry-Pick-Guide.md - "Why Use the Institute GitHub": wiki-guide/Why-use-the-Institute-GitHub.md - Hugging Face Guide: - "Repo Guide": wiki-guide/Hugging-Face-Repo-Guide.md