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

[shmonks]

Dependency

• 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

• Add missing documentation to the PR review guide #419
• Add missing documentation on how to combine migrations in Django #421
• Add missing documentation on how to quickly checkout a PR #422
• Add missing documentation on how to add an alias in GitHub #423
• Adding missing documentation on how to resolve migration conflicts #424

Action Items

• 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 should it go?
[REPLACE WITH URL OR INDICATE NEW PAGE AND PARENT PAGE]

####  When 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]

• Fill out as many of the template's fields as possible.
• 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 Missing Documentation on how to apply changes from one file to another in Github #443

[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):

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 should it go?

[REPLACE WITH URL OR INDICATE NEW PAGE AND PARENT PAGE]

When 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