From dda279dfe61cffc0cae790a6f46b10f0b75c56fe Mon Sep 17 00:00:00 2001 From: noroadsleft Date: Wed, 18 Jul 2018 14:14:35 -0700 Subject: [PATCH 1/8] Docs: newbs_learn_more_resources.md: formatting --- docs/newbs_learn_more_resources.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/newbs_learn_more_resources.md b/docs/newbs_learn_more_resources.md index 23b99f470fe6..59500b09f228 100644 --- a/docs/newbs_learn_more_resources.md +++ b/docs/newbs_learn_more_resources.md @@ -1,13 +1,15 @@ # Learning Resources -These resources are aimed at giving new members in the qmk community more understanding to the information provided in the newbs docs. + +These resources are aimed at giving new members in the QMK community more understanding to the information provided in the newbs docs. Git resources: * [Great General Tutorial](https://www.codecademy.com/learn/learn-git) * [Git Game To Learn From Examples](https://learngitbranching.js.org/) * [Git Resources to Learn More About Github](getting_started_github.md) -* [Git Resources Aimed Specificly toward QMK](contributing.md) +* [Git Resources Aimed Specifically toward QMK](contributing.md) Command Line resources: + * [Good General Tutorial on Command Line](https://www.codecademy.com/learn/learn-the-command-line) From a13b3ef744143a1b5f6e6c8a6cd460b9fa4e704d Mon Sep 17 00:00:00 2001 From: noroadsleft Date: Wed, 12 Sep 2018 04:23:33 -0700 Subject: [PATCH 2/8] Added QMK Git Conventions doc, initial version --- docs/contributing_qmk.md | 59 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 docs/contributing_qmk.md diff --git a/docs/contributing_qmk.md b/docs/contributing_qmk.md new file mode 100644 index 000000000000..012ad32673e9 --- /dev/null +++ b/docs/contributing_qmk.md @@ -0,0 +1,59 @@ +# QMK Git Conventions, or alternatively, "Git, QMK, and You: Avoiding Common Pitfalls with Contributions" + +This document walks through the process of contributing to QMK, detailing some ways to make this task easier. + +This document assumes a few things: + +1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github.md) to your account. +2. You've [set up your build environment](newbs_getting_started.md?id=environment-setup). + +## Your fork's master: Update Often, Commit Never + +It is highly recommended for QMK development, regardless of what is being done or where, to keep your `master` branch updated, but ***never*** commit to it. Instead, do all your changes in a development branch and issue pull requests from your branches when you're developing. + +To reduce the chances of merge conflicts — instances where two or more users have edited the same part of a file concurrently — keep your `master` branch relatively up-to-date, and start any new developments by creating a new branch. + +### Updating your master branch + +To keep your `master` branch updated, it is recommended to add the QMK Firmware repository as a remote repository in git. To do this, enter `git remote add upstream https://github.com/qmk/qmk_firmware.git` in your Git command line interface. To verify that the repository has been added, run `git remote -v`, which should return the following: + +``` +$ git remote -v +origin https://github.com//qmk_firmware.git (fetch) +origin https://github.com//qmk_firmware.git (push) +upstream https://github.com/qmk/qmk_firmware.git (fetch) +upstream https://github.com/qmk/qmk_firmware.git (push) +``` + +Now that this is done, you can check for updates to the repository by running `git fetch upstream`. This retrieves the list of commits to QMK's `master` branch- nicknamed `upstream` - which then can be compared to your own fork, nicknamed `origin`. To update your fork's master, run: + +``` +git checkout master +git pull upstream master +git push origin master +``` + +This switches you to your `master` branch, downloads the current QMK `master` branch, and uploads it to your fork. + +## Making Changes + +To make changes, create a new branch by entering `git checkout -b dev_branch`, which creates a new branch named `dev_branch` and checks it out. You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make. By default `git checkout -b` will base your new branch on your currently-checked-out branch. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command: + +``` +git checkout -b dev_branch master +``` + +Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's staging area, and then commit them to your branch: + +``` +git add path/to/updated_file +git commit -m "My commit message." +``` + +Use descriptive commit messages so you can know what was changed at a glance. + +!> If you've changed a lot of files, but all the files are part of the same change, you can use `git add .` to add all the changed files that are in your current directory, rather than having to add each file individually. + +## Publishing Your Changes + +The last step is to push your changes to your fork. To do this, enter `git push -u origin dev_branch`. This tells git to publish the current state of `dev_branch` to GitHub, and to use `dev_branch` on `origin` as the GitHub-hosted mirror of your local repo (the files on your computer's hard drive). You'll only need to do this once. If you make any more commits to the same branch, you only need to run `git push`; Git will know where to publish your changes. From 0bbaa75d787bcca1d535d409adcd6bc350113690 Mon Sep 17 00:00:00 2001 From: noroadsleft Date: Thu, 13 Sep 2018 15:36:27 -0700 Subject: [PATCH 3/8] Renamed contributing_qmk.md to newbs_best_practices.md --- docs/{contributing_qmk.md => newbs_best_practices.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{contributing_qmk.md => newbs_best_practices.md} (100%) diff --git a/docs/contributing_qmk.md b/docs/newbs_best_practices.md similarity index 100% rename from docs/contributing_qmk.md rename to docs/newbs_best_practices.md From a3d355430f2f8cc4ac8e00d9470a18d737a7e5f9 Mon Sep 17 00:00:00 2001 From: noroadsleft Date: Thu, 13 Sep 2018 15:57:01 -0700 Subject: [PATCH 4/8] Updated per review by @drashna --- docs/newbs_best_practices.md | 42 ++++++++++++++++++++++++++++-------- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/docs/newbs_best_practices.md b/docs/newbs_best_practices.md index 012ad32673e9..9ab930e479a5 100644 --- a/docs/newbs_best_practices.md +++ b/docs/newbs_best_practices.md @@ -1,6 +1,8 @@ -# QMK Git Conventions, or alternatively, "Git, QMK, and You: Avoiding Common Pitfalls with Contributions" +# Best Practices -This document walks through the process of contributing to QMK, detailing some ways to make this task easier. +## Or, "How I Learned to Stop Worrying and Love Git." + +This document aims to instruct novices in the best ways to have a smooth experience in contributing to QMK. We will walk through the process of contributing to QMK, detailing some ways to make this task easier, and then later we'll break some things in order to teach you how to fix them. This document assumes a few things: @@ -15,7 +17,13 @@ To reduce the chances of merge conflicts — instances where two or more use ### Updating your master branch -To keep your `master` branch updated, it is recommended to add the QMK Firmware repository as a remote repository in git. To do this, enter `git remote add upstream https://github.com/qmk/qmk_firmware.git` in your Git command line interface. To verify that the repository has been added, run `git remote -v`, which should return the following: +To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, enter + +``` +git remote add upstream https://github.com/qmk/qmk_firmware.git +```` + +in your Git command line interface. To verify that the repository has been added, run `git remote -v`, which should return the following: ``` $ git remote -v @@ -25,35 +33,51 @@ upstream https://github.com/qmk/qmk_firmware.git (fetch) upstream https://github.com/qmk/qmk_firmware.git (push) ``` -Now that this is done, you can check for updates to the repository by running `git fetch upstream`. This retrieves the list of commits to QMK's `master` branch- nicknamed `upstream` - which then can be compared to your own fork, nicknamed `origin`. To update your fork's master, run: +Now that this is done, you can check for updates to the repo by running `git fetch upstream`. This retrieves the branches and tags — collectively referred to as "refs" — from the QMK repo, which now has the nickname `upstream`. We can now compare the data on our fork `origin` to that held by QMK. + +To update your fork's master, run the following, hitting the Enter key after each line: ``` git checkout master +git fetch upstream git pull upstream master git push origin master ``` -This switches you to your `master` branch, downloads the current QMK `master` branch, and uploads it to your fork. +This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork. ## Making Changes -To make changes, create a new branch by entering `git checkout -b dev_branch`, which creates a new branch named `dev_branch` and checks it out. You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make. By default `git checkout -b` will base your new branch on your currently-checked-out branch. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command: +To make changes, create a new branch by entering: + +``` +git checkout -b dev_branch +git push --set-upstream origin dev_branch +``` + +This creates a new branch named `dev_branch`, checks it out, and then saves the new branch to your fork. The `--set-upstream` argument tells git to use your fork and the `dev_branch` branch every time you use `git push` or `git pull` from this branch. It only needs to be used on the first push; after that, you can safely use `git push` or `git pull`, without the rest of the arguments. + +!> With `git push`, you can use `-u` in place of `--set-upstream` — `-u` is an alias for `--set-upstream`. + +You can name your branch nearly anything you want, though it is recommended to name it something related to the changes you are going to make. + +By default `git checkout -b` will base your new branch on the branch that is checked out. You can base your new branch on an existing branch that is not checked out by adding the name of the existing branch to the command: ``` git checkout -b dev_branch master ``` -Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's staging area, and then commit them to your branch: +Now that you have a development branch, open your text editor and make whatever changes you need to make. It is recommended to make many small commits to your branch; that way, any change that causes issues can be more easily traced and undone if needed. To make your changes, edit and save any files that need to be updated, add them to Git's *staging area*, and then commit them to your branch: ``` git add path/to/updated_file git commit -m "My commit message." ``` -Use descriptive commit messages so you can know what was changed at a glance. +`git add` adds files that have been changed to Git's *staging area*, which is Git's "loading zone." This contains the changes that are going to be *committed* by `git commit`, which saves the changes to the repo. Use descriptive commit messages so you can know what was changed at a glance. !> If you've changed a lot of files, but all the files are part of the same change, you can use `git add .` to add all the changed files that are in your current directory, rather than having to add each file individually. ## Publishing Your Changes -The last step is to push your changes to your fork. To do this, enter `git push -u origin dev_branch`. This tells git to publish the current state of `dev_branch` to GitHub, and to use `dev_branch` on `origin` as the GitHub-hosted mirror of your local repo (the files on your computer's hard drive). You'll only need to do this once. If you make any more commits to the same branch, you only need to run `git push`; Git will know where to publish your changes. +The last step is to push your changes to your fork. To do this, enter `git push`. Git now publishes the current state of `dev_branch` to your fork. From 98a9dce4061291c2599f55cc4d6323e81ddd4255 Mon Sep 17 00:00:00 2001 From: noroadsleft Date: Mon, 24 Sep 2018 15:40:33 -0700 Subject: [PATCH 5/8] Added navigation links --- docs/_sidebar.md | 1 + docs/_summary.md | 2 ++ docs/newbs.md | 1 + 3 files changed, 4 insertions(+) diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 56a6463918c0..465f4657cd32 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -3,6 +3,7 @@ * [Building Your First Firmware](newbs_building_firmware.md) * [Flashing Firmware](newbs_flashing.md) * [Testing and Debugging](newbs_testing_debugging.md) + * [Best Practices](newbs_best_practices.md) * [Learning Resources](newbs_learn_more_resources.md) * [QMK Basics](README.md) diff --git a/docs/_summary.md b/docs/_summary.md index 11aeb7cd36f5..465f4657cd32 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -3,6 +3,8 @@ * [Building Your First Firmware](newbs_building_firmware.md) * [Flashing Firmware](newbs_flashing.md) * [Testing and Debugging](newbs_testing_debugging.md) + * [Best Practices](newbs_best_practices.md) + * [Learning Resources](newbs_learn_more_resources.md) * [QMK Basics](README.md) * [QMK Introduction](getting_started_introduction.md) diff --git a/docs/newbs.md b/docs/newbs.md index 38a9607d4486..e687fd227940 100644 --- a/docs/newbs.md +++ b/docs/newbs.md @@ -12,6 +12,7 @@ There are 5 main sections to this guide: * [Building Your First Firmware](newbs_building_firmware.md) * [Flashing Firmware](newbs_flashing.md) * [Testing and Debugging](newbs_testing_debugging.md) +* [Best Practices](newbs_best_practices.md) * [Learn More with these Resources](newbs_learn_more_resources.md) This guide is focused on helping someone who has never compiled software before. It makes choices and recommendations based on that viewpoint. There are alternative methods for many of these procedures, and we support most of those alternatives. If you have any doubt about how to accomplish a task you can [ask us for guidance](getting_started_getting_help.md). From 3f48e1e590f9be382cd434d35786a333c588c127 Mon Sep 17 00:00:00 2001 From: noroadsleft Date: Mon, 24 Sep 2018 15:41:22 -0700 Subject: [PATCH 6/8] Updated to Best Practices doc --- docs/newbs_best_practices.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/newbs_best_practices.md b/docs/newbs_best_practices.md index 9ab930e479a5..ccf111ce7ad2 100644 --- a/docs/newbs_best_practices.md +++ b/docs/newbs_best_practices.md @@ -17,13 +17,13 @@ To reduce the chances of merge conflicts — instances where two or more use ### Updating your master branch -To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, enter +To keep your `master` branch updated, it is recommended to add the QMK Firmware repository ("repo") as a remote repository in git. To do this, open your Git command line interface and enter: ``` git remote add upstream https://github.com/qmk/qmk_firmware.git -```` +``` -in your Git command line interface. To verify that the repository has been added, run `git remote -v`, which should return the following: +To verify that the repository has been added, run `git remote -v`, which should return the following: ``` $ git remote -v @@ -46,6 +46,7 @@ git push origin master This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork. + ## Making Changes To make changes, create a new branch by entering: From 0d648bd1aaa920760eb4ba0172ab86fb5d64055d Mon Sep 17 00:00:00 2001 From: noroadsleft Date: Mon, 24 Sep 2018 15:43:40 -0700 Subject: [PATCH 7/8] Minor updates to Learn More Resources doc Markdown formatting consistency because I'm particular about it. --- docs/newbs_learn_more_resources.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/newbs_learn_more_resources.md b/docs/newbs_learn_more_resources.md index 59500b09f228..9b77db8fd428 100644 --- a/docs/newbs_learn_more_resources.md +++ b/docs/newbs_learn_more_resources.md @@ -1,6 +1,6 @@ # Learning Resources -These resources are aimed at giving new members in the QMK community more understanding to the information provided in the newbs docs. +These resources are aimed at giving new members in the QMK community more understanding to the information provided in the Newbs docs. Git resources: From b675bc9c3f278a5080debf8e9321b692fb1aa985 Mon Sep 17 00:00:00 2001 From: noroadsleft Date: Sat, 13 Oct 2018 19:42:41 -0700 Subject: [PATCH 8/8] Added Merge Conflict section to Best Practices doc --- docs/newbs_best_practices.md | 85 ++++++++++++++++++++++++++++++++++-- 1 file changed, 82 insertions(+), 3 deletions(-) diff --git a/docs/newbs_best_practices.md b/docs/newbs_best_practices.md index ccf111ce7ad2..61bcc0c6adb8 100644 --- a/docs/newbs_best_practices.md +++ b/docs/newbs_best_practices.md @@ -9,6 +9,7 @@ This document assumes a few things: 1. You have a GitHub account, and have [forked the qmk_firmware repository](getting_started_github.md) to your account. 2. You've [set up your build environment](newbs_getting_started.md?id=environment-setup). + ## Your fork's master: Update Often, Commit Never It is highly recommended for QMK development, regardless of what is being done or where, to keep your `master` branch updated, but ***never*** commit to it. Instead, do all your changes in a development branch and issue pull requests from your branches when you're developing. @@ -46,8 +47,7 @@ git push origin master This switches you to your `master` branch, retrieves the refs from the QMK repo, downloads the current QMK `master` branch to your computer, and then uploads it to your fork. - -## Making Changes +### Making Changes To make changes, create a new branch by entering: @@ -79,6 +79,85 @@ git commit -m "My commit message." !> If you've changed a lot of files, but all the files are part of the same change, you can use `git add .` to add all the changed files that are in your current directory, rather than having to add each file individually. -## Publishing Your Changes +### Publishing Your Changes The last step is to push your changes to your fork. To do this, enter `git push`. Git now publishes the current state of `dev_branch` to your fork. + + +## Resolving Merge Conflicts + +Sometimes when your work in a branch takes a long time to complete, changes that have been made by others conflict with changes you have made to your branch when you open a pull request. This is called a *merge conflict*, and is what happens when multiple people edit the same parts of the same files. + +### Rebasing Your Changes + +A *rebase* is Git's way of taking changes that were applied at one point, reversing them, and then applying the same changes to another point. In the case of a merge conflict, you can rebase your branch to grab the changes that were made between when you created your branch and the present time. + +To start, run the following: + +``` +git fetch upstream +git rev-list --left-right --count HEAD...upstream/master +``` + +The `git rev-list` command entered here returns the number of commits that differ between the current branch and QMK's master branch. We run `git fetch` first to make sure we have the refs that represent the current state of the upstream repo. The output of the `git rev-list` command entered returns two numbers: + +``` +$ git rev-list --left-right --count HEAD...upstream/master +7 35 +``` + +The first number represents the number of commits on the current branch since it was created, and the second number is the number of commits made to `upstream/master` since the current branch was created, and thus, the changes that are not recorded in the current branch. + +Now that the current states of both the current branch and the upstream repo are known, we can start a rebase operation: + +``` +git rebase upstream/master +``` + +This tells Git to undo the commits on the current branch, and then reapply them against QMK's master branch. + +``` +$ git rebase upstream/master +First, rewinding head to replay your work on top of it... +Applying: Commit #1 +Using index info to reconstruct a base tree... +M conflicting_file_1.txt +Falling back to patching base and 3-way merge... +Auto-merging conflicting_file_1.txt +CONFLICT (content): Merge conflict in conflicting_file_1.txt +error: Failed to merge in the changes. +hint: Use 'git am --show-current-patch' to see the failed patch +Patch failed at 0001 Commit #1 + +Resolve all conflicts manually, mark them as resolved with +"git add/rm ", then run "git rebase --continue". +You can instead skip this commit: run "git rebase --skip". +To abort and get back to the state before "git rebase", run "git rebase --abort". +``` + +This tells us that we have a merge conflict, and gives the name of the file with the conflict. Open the conflicting file in your text editor, and somewhere in the file, you'll find something like this: + +``` +<<<<<<< HEAD +

For help with any issues, email us at support@webhost.us.

+======= +

Need help? Email support@webhost.us.

+>>>>>>> Commit #1 +``` + +The line `<<<<<<< HEAD` marks the beginning of a merge conflict, and the `>>>>>>> Commit #1` line marks the end, with the conflicting sections separated by `=======`. The part on the `HEAD` side is from the QMK master version of the file, and the part marked with the commit message is from the current branch and commit. + +Because Git tracks *changes to files* rather than the contents of the files directly, if Git can't find the text that was in the file previous to the commit that was made, it won't know how to edit the file. Re-editing the file will solve the conflict. Make your changes, and then save the file. + +``` +

Need help? Email support@webhost.us.

+``` + +Now run: + +``` +git add conflicting_file_1.txt +git rebase --continue +``` + +Git logs the changes to the conflicting file, and continues applying the commits from our branch until it reaches the end.