From 0c41dc36bca07b7d184ece9c1ee92b4ad537ca79 Mon Sep 17 00:00:00 2001 From: egrace479 Date: Thu, 9 Oct 2025 09:20:14 -0400 Subject: [PATCH 1/8] Preliminary git cherry-pick guide based on updating Imageomics Guide from Collab template --- docs/wiki-guide/Git-Cherry-Pick-Guide.md | 56 ++++++++++++++++++++++++ mkdocs.yaml | 1 + 2 files changed, 57 insertions(+) create mode 100644 docs/wiki-guide/Git-Cherry-Pick-Guide.md 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..269fe2a --- /dev/null +++ b/docs/wiki-guide/Git-Cherry-Pick-Guide.md @@ -0,0 +1,56 @@ +# Git Cherry-pick update for Downstream Repos + +A step-by-step guide to updating repositories based on the template guide repo: + +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 updated 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 `, ex: + + ```console + git cherry-pick 22afb3bcafeefe25bb9f9d5a96b4ac109b9d04cc + ``` + + !!! note + If you have a merge commit, 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. Merge commit the PR—**Do Not** squash or rebase the PR, then you would lose the ability to find the original source and context for the selected commits (the purpose of using a `git cherry-pick` instead of just adding the file). diff --git a/mkdocs.yaml b/mkdocs.yaml index a892776..07fc9f4 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -108,6 +108,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 # May want to personalize (on page as well): Why use the GitHub - "Why Use the Organization GitHub": wiki-guide/Why-use-the-organization-GitHub.md - Hugging Face Guide: From 028b592c7817ae25811e8b1d06c75408600f752f Mon Sep 17 00:00:00 2001 From: egrace479 Date: Mon, 3 Nov 2025 13:07:02 -0500 Subject: [PATCH 2/8] Revise directions for improved clarity and links in downstream repos --- docs/wiki-guide/Git-Cherry-Pick-Guide.md | 35 ++++++++++++++++++++---- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/docs/wiki-guide/Git-Cherry-Pick-Guide.md b/docs/wiki-guide/Git-Cherry-Pick-Guide.md index 269fe2a..a0bfc72 100644 --- a/docs/wiki-guide/Git-Cherry-Pick-Guide.md +++ b/docs/wiki-guide/Git-Cherry-Pick-Guide.md @@ -2,9 +2,10 @@ A step-by-step guide to updating repositories based on the template guide repo: -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. +!!! 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. +1. **Ensure the target repo is up-to-date.** 2. Create a new branch onto which to pull the changes: ```console @@ -41,16 +42,40 @@ Before you start, you should know which commits are going to be pulled from the ``` 4. Run `git fetch upstream` to get the commits from the template repo (now recognized as `upstream`). -5. Run `git cherry-pick `, ex: +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 22afb3bcafeefe25bb9f9d5a96b4ac109b9d04cc + 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". Finally, select ++esc++ and type `:wq` to complete the commit message edit. + !!! note If you have a merge commit, 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. Merge commit the PR—**Do Not** squash or rebase the PR, then you would lose the ability to find the original source and context for the selected commits (the purpose of using a `git cherry-pick` instead of just adding the file). +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. From b003d20056d0cf182fecbad6fc3f158883c6262e Mon Sep 17 00:00:00 2001 From: egrace479 Date: Mon, 3 Nov 2025 13:15:15 -0500 Subject: [PATCH 3/8] fix typo, clarify info box --- docs/wiki-guide/Git-Cherry-Pick-Guide.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/wiki-guide/Git-Cherry-Pick-Guide.md b/docs/wiki-guide/Git-Cherry-Pick-Guide.md index a0bfc72..4fee66a 100644 --- a/docs/wiki-guide/Git-Cherry-Pick-Guide.md +++ b/docs/wiki-guide/Git-Cherry-Pick-Guide.md @@ -49,16 +49,16 @@ A step-by-step guide to updating repositories based on the template guide repo: ``` 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 @@ -68,10 +68,10 @@ A step-by-step guide to updating repositories based on the template guide repo: ... ``` - The URL will render as "Imageomics/Collaborative-distributed-science-guide#29". Finally, select ++esc++ and type `:wq` to complete the commit message edit. + 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. - !!! note - If you have a merge commit, 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. + !!! 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. From 14bb3feb92eb1fbdfebb2523219e7569b09524e9 Mon Sep 17 00:00:00 2001 From: egrace479 Date: Wed, 12 Nov 2025 18:14:15 -0500 Subject: [PATCH 4/8] Add link to cherry-pick guide for instructions on updating personalized sites --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4b877fb..727ef49 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Please feel free to open an [issue](https://github.com/Imageomics/Collaborative- This Guide is set up as a template repository such that there are two primary means of interacting with it: -1. Building a personalized version of the Guide: select "Use this Template" at the top of the repo to generate your own version. This will create a new repository (generated from the template repo) that does _not_ share the commit history of the template. Updates could still be added from the template upstream through [`git cherry-pick`](https://git-scm.com/docs/git-cherry-pick). More details are provided below, in [Personalizing the Guide](#personalizing-the-guide). +1. Building a personalized version of the Guide: select "Use this Template" at the top of the repo to generate your own version. This will create a new repository (generated from the template repo) that does _not_ share the commit history of the template. Updates can still be added from the template upstream through `git cherry-pick` ([instructions](docs/wiki-guide/Git-Cherry-Pick-Guide.md)). More details are provided below, in [Personalizing the Guide](#personalizing-the-guide). 2. Contributing to the Guide: fork this repo, make changes, and submit a pull request (PR) for review. Some guidance is provided in the [Pull Request Guide](https://imageomics.github.io/Collaborative-distributed-science-guide/wiki-guide/The-GitHub-Pull-Request-Guide/); please provide a detailed description of your changes and review the contributing guidelines (coming soon). ### Personalizing the Guide From a981e4238bdd6c0d0a06e3873c40b716662e9443 Mon Sep 17 00:00:00 2001 From: egrace479 Date: Wed, 12 Nov 2025 18:15:25 -0500 Subject: [PATCH 5/8] Fix typo in acknowledgments --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 727ef49..f02eb14 100644 --- a/README.md +++ b/README.md @@ -59,4 +59,4 @@ This guide was developed alongside the [Imageomics Guide](https://imageomics.git ## 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. From 6739d3296c987648706f2ea83ee01720bb51c42b Mon Sep 17 00:00:00 2001 From: egrace479 Date: Tue, 18 Nov 2025 10:38:40 -0500 Subject: [PATCH 6/8] Clarify description and add link to cherry-pick guide for more info --- docs/wiki-guide/Two-Repo-Problem.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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. From 2fd017cd1f3628783c7b384cbcf31f52db171c6d Mon Sep 17 00:00:00 2001 From: egrace479 Date: Tue, 18 Nov 2025 10:39:06 -0500 Subject: [PATCH 7/8] Add some intro to the page --- docs/wiki-guide/Git-Cherry-Pick-Guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki-guide/Git-Cherry-Pick-Guide.md b/docs/wiki-guide/Git-Cherry-Pick-Guide.md index 4fee66a..94d8581 100644 --- a/docs/wiki-guide/Git-Cherry-Pick-Guide.md +++ b/docs/wiki-guide/Git-Cherry-Pick-Guide.md @@ -1,6 +1,6 @@ # Git Cherry-pick update for Downstream Repos -A step-by-step guide to updating repositories based on the template guide repo: +`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. This can be helpful when forking another repo or building off an evolving template, such as this guide. Below, we provide a step-by-step guide to updating repositories based on the template guide repo: !!! 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. From 1ffad08dde7e2f93901bf57964c3be87adc92adb Mon Sep 17 00:00:00 2001 From: Elizabeth Campolongo <38985481+egrace479@users.noreply.github.com> Date: Tue, 18 Nov 2025 10:50:13 -0500 Subject: [PATCH 8/8] Add a little extra context/clarity Co-authored-by: Matt Thompson <31709066+thompsonmj@users.noreply.github.com> --- docs/wiki-guide/Git-Cherry-Pick-Guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/wiki-guide/Git-Cherry-Pick-Guide.md b/docs/wiki-guide/Git-Cherry-Pick-Guide.md index 94d8581..e70d4f4 100644 --- a/docs/wiki-guide/Git-Cherry-Pick-Guide.md +++ b/docs/wiki-guide/Git-Cherry-Pick-Guide.md @@ -1,6 +1,6 @@ # 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. This can be helpful when forking another repo or building off an evolving template, such as this guide. Below, we provide a step-by-step guide to updating repositories based on the template guide repo: +`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 this guide. Below, we provide a step-by-step guide to updating repositories based on the template guide repo: !!! 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.