Add missing documentation on how to apply changes from one file to another in GitHub

[shmonks]

Dependency

• [x] Information missing on how to apply changes across files in GitHub

Overview

We need to make it easy to:

• Record any missing documentation on how to apply changes across files in GitHub
• Keep those records in one place
• Create new issues based on those records

This issue is the place to record missing documentation and start creating related new issues.

Details

• We are striving to write documentation that helps developers use GitHub.
• This issue tracks the documentation that needs to be added on how to apply changes across files in GitHub. If you've noticed missing documentation about other Git and/or Django processes,

see the following issues instead

- #419 - #421 - #422 - #423 - #424

Action Items

• [x] For each piece of missing information, copy and paste the following template into a new comment below.

  
  ### Overview
  We need to add [REPLACE WITH WHAT NEEDS ADDING], so that developers can [REPLACE WITH BENEFIT]

Action Items

• [ ] [REPLACE WITH ACTION ITEMS]

Resources/Instructions/Tags

1.0x [REPLACE WITH LINKS TO ANY EXTERNAL DOCS THAT MIGHT BE USEFUL (WITH INSTRUCTIONS, IF NEEDED)] 1.0x [REPLACE WITH ANY RELEVANT TAGS e.g., git, django, etc.]

Documentation Addition Notes

What's missing?

[REPLACE WITH DESCRIPTION OF WHAT'S MISSING FROM THE DOCUMENTATION]

Where would this information have been useful?

[REPLACE WITH LINK TO THE PR/ISSUE/SITUATION THAT PROMPTED THE NEED FOR THIS CHANGE/ADDITION]

Which roles will benefit most from this information?

[REPLACE WITH ROLES]

- [x] Fill out as many of the template's fields as possible. 
- [x] Copy and paste a link to your comment in **Section 2: List of comments/issues about missing documentation on how to apply changes across files in GitHub** below, using the next available number
- [ ] Copy the content of your comment
- [ ] Create a new issue, pasting the content of your comment into the new issue
- Add the following labels to the new issue
   - [ ] `feature: docs: PD team documentation`
   - [ ] `size: 0.25pt`
   - [ ] `s: PD team`
   - [ ] `ready for dev lead`
   - [ ] choose a complexity label that fits
   - [ ] choose the role label that fits
- [ ] When this new issue has been created, add a link to it in **Section 2: List of comments/issues about missing documentation on how to apply changes across files in GitHub** below. Make sure the link to your new issue appears beneath the link to your comment, so we can ensure that all comments get made into issues
- [ ] Hide the original comment (you can mark it 'Resolved')

### Section 2: List of comments/issues about missing documentation on how to apply changes across files in GitHub
- 2.01 https://github.com/hackforla/peopledepot/issues/425#issuecomment-2450885410
   - 2.01.01 # [REPLACE WITH ISSUE NUMBER ONCE COMMENT IS MADE INTO ISSUE]
- 2.02 [REPLACE with link to your comment below]
   - 2.02.0x # [REPLACE WITH ISSUE NUMBER ONCE COMMENT IS MADE INTO ISSUE

[shmonks]

What's missing?

• [ ] A description of how to apply changes from one GitHub file to another

Where would this information have been useful?

• [ ] Any situation in which you've made changes to a file and the place of change has been moved to a different file in main. For example, you've made changes to CONTRIBUTING.md in a GitHub branch, after you copied content from that file to another file (e.g.,docs/contributing/dev_environment.md). You want to apply the changes you made to CONTRIBUTING.md to docs/contributing/dev_environment.md as well.

Which roles will benefit most from this information?

• [ ] Backend/Dev

Relevant resources and tags

• [ ] Here's how to apply changes from one GitHub file to another:

1. Rebase/Merge your feature branch to main.

2. Undo changes to the file you changed (replacing CONTRIBUTING.md with the relevant filename):

   git reset upstream/main -- CONTRIBUTING.md

3. Now switch to the unmerged branch with the changes (replacing our-branch-original with the relevant branch name):

   git switch our-branch-original

4. Create a patch of the changes (replacing with relevant filename):

   
   git format-patch hackforla/main CONTRIBUTING.md
   # only changes to CONTRIBUTING.md
   # include changes since we branched off from hackforla/main
   # may need to create a temporary branch where hackforla/main used to be for this command

output:

0001-add-to-dev-environment.patch

5. Switch to the rebased branch without the changes to the file (in this example `CONTRIBUTING.md`):
```bash
git switch our-branch-rebased

6. Apply the patch to the other file (in this example, docs/contributing/dev_environment.md:

   patch -p1 docs/contributing/dev_environment.md 0001-add-to-dev-environment.patch

• [ ] Tags: git, diff, patch, moved content

[shmonks]

• @fyliu, could you read through this comment and let me know if it represents the process you want documented? I'm not sure I understood the scenario you described. https://github.com/hackforla/peopledepot/issues/425#issuecomment-2436306839

[fyliu]

@shmonks, I'll try to rephrase that here to see if it becomes more understandable. It made sense until you read it weeks later...

Where would this information have been useful?

This is the scenario:

1. You made a change to CONTRIBUTING.md, unmerged.

2. Another dev split CONTRIBUTING.md into several files and it's merged into main.

   • The place you made the change in CONTRIBUTING.md is now in a file called contributing/dev_environment.md
   • git can't merge your change automatically. (git tracks renames, but not splits)

3. You can re-type (copy/paste) the change manually into contributing/dev_environment.md, or you can use a patch to apply the change semi-automatically.

This guide is useful for the more complex changes.

[shmonks]

Overview

We need to add a description of how to apply changes from one GitHub file to another, so that developers can synchronize changes and keep files up-to-date.

Action Items

• [ ] Add content in the What's missing? section below to a new numbered item and linked page here: https://hackforla.github.io/peopledepot/contributing/howto/, editing or revising if necessary

Resources/Instructions/Tags

1.01 git, diff, patch, moved content

Documentation Addition Notes

What's missing?

• [ ] Here's how to apply changes from one GitHub file to another:

1. Rebase/Merge your feature branch to main.

2. Undo changes to the file you changed (replacing CONTRIBUTING.md with the relevant filename):

   git reset upstream/main -- CONTRIBUTING.md

3. Now switch to the unmerged branch with the changes (replacing our-branch-original with the relevant branch name):

   git switch our-branch-original

4. Create a patch of the changes (replacing with relevant filename):

   
   git format-patch hackforla/main CONTRIBUTING.md
   # only changes to CONTRIBUTING.md
   # include changes since we branched off from hackforla/main
   # may need to create a temporary branch where hackforla/main used to be for this command

output:

0001-add-to-dev-environment.patch

5. Switch to the rebased branch without the changes to the file (in this example `CONTRIBUTING.md`):
```bash
git switch our-branch-rebased

6. Apply the patch to the other file (in this example, docs/contributing/dev_environment.md:

   patch -p1 docs/contributing/dev_environment.md 0001-add-to-dev-environment.patch

Where would this information have been useful?

• This information would be useful in situations where complex changes have been made - for example::
  1. You made a change to CONTRIBUTING.md, unmerged.
  2. Another dev split CONTRIBUTING.md into several files and it's merged into main.
     • The place you made the change in CONTRIBUTING.md is now in a file called contributing/dev_environment.md
     • git can't merge your change automatically. (git tracks renames, but not splits)
  3. By using the patch described above to apply the change semi-automatically, you can avoid having to type (copy/paste) the change manually into contributing/dev_environment.md

Which roles will benefit most from this information?

• Backend/Dev