Documentation on merging

[MichaelPachec0]

It has come to my attention that for more intricate issues, there have been issues with sending PRs to the repository.
I will outline 3 ways to create clean PRs and their pros and cons.

1. Deleting and reforking from Upstream (this repository).
   I figure most of you know how to do this and probably are doing this.

• Steps:

  1. Backup your work you have done.
  2. Delete your local and remote forks.
  3. Refork this repository and clone locally
  4. Create a new branch and then insert your updated code.
  5. Commit the code in question and publish a PR to this repository.

• Pros:
  - Extremely easy to do
  - Can be automated
  - Do not have to worry about git getting in the way of committing

• Cons:

  • Git isnt getting in the way when committing
    • Whenever there are mismatches between your branch and main master branch concerning changes, attention should be paid to such changes. There is usually a good reason why git complains about this.
    • There might be code that has changed, this way of doing things can possibly create a broken version of the repository if the code is not reviewed carefully
  • There is a much better way of doing this without reforking.
    1. we can update the master branch locally
    • git fetch origin master:master can be used to update the master branch even if you are not in the same branch
    2. save your work
    3. delete your branch
    • git branch -D <branch-name>
      • make sure you have saved your changes, any changes that are in your remote
    4. remake your branch
    • git checkout -b <branch-name> master
      • If you using the same branch-name as the deleted one, then you are going to use --force when pushing
    5. Insert your backed up code and commit it locally
    6. Now its time to push it to your repository
    • This is where if you named the branch the same as the deleted one where --force
    • Warning: Be careful this will tell git to ignore differences between what is on your local repository and the remote on github
    • If you are confident with that you are ready to push you can either push each branch one by one or push them all at the same time
      • the command to do them all at once is git push origin --all remembering that you need --force if your deleted branch and new branch are the same.
      • this ensures that your master and any branches you were working on are in sync with the remote
    7. You can then follow opening a PR using the site in github.

2. Better way 1: using git merge.
   • Steps:
     1. Update the master branch locally
        • git fetch upstream master:master can be used to update the master branch even if you are not in the same branch
          • make sure that you have my branch set to upstream git remote add upstream git@github.com:MichaelPachec0/nodejs-project-night.git
     2. we merge the master into your working branch
        • git merge master --no-edit will do this
     3. There is a chance that there will be scary error messages. If so go back to vscode, there should be files in the explorer that will have a ! next to them, review the conflicting changes and decide you want keep the changes that master has (Accept Current Change) or if you want your code to overwrite whats currently in master (Accept Incoming Changes). Once you have fixed all the conflicts in a file, make sure you save the file and go to the next one. If you are unsure, you can contact me or ask in group chat and ask.
     4. At anytime if you feel like you made a mistake you can always back out
        • git merge --abort will do this for you and you can start over.
     5. Once all the conflicting changes are fixed go back to your terminal and let git know it can continue
        • git merge --continue --no-edit
     6. Now branch should be clean and ready to push.
     7. Time to open a PR on github.
   • Pros:
     • It is less prone to give you problems compared to the next way.
     • You dont need to go through all the hassle of deleting and reforking.
     • Git will warn you when there are conflicting changes.
   • Cons:
     • There is more work when merging.
     • Merging can be can have scary looking messages, and sometimes you dont know whether or not you overwrite whats on master.
     • There will be merge commits on top of your actual work, which might make it slightly annoying to review
3. Better way 2: using git rebase.
   • Steps:
     1. Update the master branch locally
        • git fetch upstream master:master can be used to update the master branch even if you are not in the same branch
          • make sure that you have my branch set to upstream git remote add upstream git@github.com:MichaelPachec0/nodejs-project-night.git
     2. we merge the master into your working branch this time using rebase
        • git rebase master
     3. There very likely chance that rebase will complain output scary messages in the terminal. as with "Better way 1", use vscode to go over the changes.
     4. Once all the conflicting changes are resolved go back to your terminal and add the files that have edited
        • use git status to see which files have been marked as modified
        • git add \<file\> to add the files, or all at once using git add -u
     5. You are ready to tell git to continue.
        • git rebase --continue
        • This will open an editor in case you want to edit your commit
          • If you dont want this to happen you can do this - ref https://stackoverflow.com/a/45783848
            • git -c core.editor=true rebase --continue
     6. Time to push.
     7. Making sure that everything worked, open a PR with the changes ready to be merged.
   • Pros:
     • Same as "Better way 1" except you will get more warnings
     • A big plus is that only the commits that matter get pushed, meaning no extra merging commits
   • Cons:
     • Same as "Better way 1" with the exception of getting more warnings and more work
     • Much more work, im not kidding on this

[MichaelPachec0]

ugh just to make sure that the documentation is correct, there was a mistake in the docs where it was not specified that it was needed to have this repo added as a remote and that it was needed to specify the remote repository (in this case upstream) when fetching. It meant that everyone wasn't pulling from the latest sources. Well that is fixed now in the documentation.