Permalink
Browse files

Updated texts around abandoned PR's (#413)

- Updated texts around abandoned PR's (issue #412).
- Updated texts around PR's waiting for CLA.
- Minor updates to texts.
  • Loading branch information...
johlju committed Jul 7, 2018
1 parent b77b67c commit 4834310b72d8917d3ce44bbe3ccaf81a4ccc7117
Showing with 65 additions and 47 deletions.
  1. +46 −37 GettingStartedWithGitHub.md
  2. +19 −10 Maintainers.md
@@ -15,7 +15,7 @@
- [Resolve merge conflicts](#resolve-merge-conflicts)
- [Delete a branch](#delete-a-branch)
- [Using .gitignore to exclude files and/or folders](#using-gitignore-to-exclude-files-andor-folders)
- [How to continue working on a pull request when an author (contributor) is unable to complete it](#how-to-continue-working-on-a-pull-request-when-an-author-contributor-is-unable-to-complete-it)
- [How to continue working on a pull request (PR) when an author (contributor) is unable to complete it](#how-to-continue-working-on-a-pull-request-pr-when-an-author-contributor-is-unable-to-complete-it)
## Register on GitHub
@@ -36,9 +36,9 @@ During install:
You will have two option for Git command line: "powershell.exe" or "Git Bash". Open one of them.
1. If you use `powershell.exe`, you may want to install [posh-git](https://github.com/dahlbyk/posh-git) module (adds tab-completion and branch name to prompt).
2. Git command line often ask for interactive input, which makes powershell_ise.exe bad choice for Git command line (has native tab-completion and branch name in prompt out-of-the-box).
**Warning**: Git Bash is based on MINGW32, so you need to use linux-style paths.
I.e. `cd /c/Windows`, instead of `cd c:\Windows`.
2. Git command line often ask for interactive input, which makes powershell_ise.exe bad choice for Git command line (has native tab-completion and branch name in prompt out-of-the-box).
**Warning**: Git Bash is based on MINGW32, so you need to use linux-style paths.
I.e. `cd /c/Windows`, instead of `cd c:\Windows`.
## Setup Git
@@ -56,14 +56,14 @@ git config --global core.autocrlf true
```
## Setup SSH key
To avoid typing username and password all the time,
To avoid typing username and password all the time,
you may [setup ssh-key authentication](https://help.github.com/articles/generating-ssh-keys/) for you GitHub account.
This setup is per machine.
## Clone repository from GitHub
Open GitHub repository of a module.
Open GitHub repository of a module.
To find, it you can go to all [`xDscResources`](xDscResources) or search in [PowerShell GitHub org repos](https://github.com/PowerShell).
I.e. if you want to contribute to **xActiveDirectory** you can do the following
@@ -125,7 +125,7 @@ origin https://github.com/PowerShell/xActiveDirectory (push)
## Making changes and pushing them to the fork
* To make changes, create a new local branch: `git checkout -b <branch> my/dev`, i.e. `git checkout -b awesome_feature my/dev`.
* To make changes, create a new local branch: `git checkout -b <branch> my/dev`, i.e. `git checkout -b awesome_feature my/dev`.
This will create a new local branch, connect to your fork's dev branch as the tracking branch (upstream branch) and then checkout (move) to the new branch.
* To see all branches, run `git branch -a`
* To see status of all branches (if they are ahead or behind the tracking branch) , run `git branch -v`
@@ -149,7 +149,7 @@ Active branch is marked with `*`.
* After that can **push** changes to your fork with `git push my <branch>` command, i.e. `git push my awesome_feature`.
## Creating a new pull request
Now you should be able to see your branch in your fork on GitHub
![GitHub-Select-Branch.png](Images/GitHub-Select-Branch.png)
@@ -174,10 +174,10 @@ GitHub would automatically update the pull request.
## Resolve merge conflicts
If another pull request is merged while yours is in review, you will need to add those new changes into your working branch before your pull request is allowed to merge. To do this we will 'rebase' the branch.
This means that the changes you made in your working branch for your pull request will be 'replayed' on top of the changes that were recently merged into dev, as though you originally created your branch/fork from the current point that the dev branch is at.
This means that the changes you made in your working branch for your pull request will be 'replayed' on top of the changes that were recently merged into dev, as though you originally created your branch/fork from the current point that the dev branch is at.
_Note: Since it's replayed you might get conflicts several times during the rebase process (for the first `rebase` command, and for each following `rebase --continue`)._
Here are the steps to rebasing your branch:
Here are the steps to rebasing your branch:
**_Note: These steps require that you have added the remote as described above. Run `git remote -v` to verify that you have the remotes `my` pointing to your fork repository and `origin` pointing to the original repository._**
1. Rebase the local dev branch from the base dev branch.
@@ -186,20 +186,20 @@ Here are the steps to rebasing your branch:
4. Resolve merge conflicts.
5. Update your pull request.
### 1. Rebase the local dev branch from the base dev branch
### 1. Rebase the local dev branch from the base dev branch
* In a PowerShell prompt, you need to do the following.
```
cd <path to cloned repository> # This is the path to your cloned repository. I.e. cd C:\Source\xActiveDirectory
git checkout dev # Checkout (move) to your local dev branch.
git fetch origin dev # Get all changes from origin/dev (and branch information).
git fetch origin dev # Get all changes from origin/dev (and branch information).
git rebase origin/dev # Rebase changes from origin/dev into your local dev branch.
```
**NOTE! You can get merge conflicts that need to be resolved before you continue with the next step of rebasing your working branch. Search for the word 'CONFLICT' in the output. See step 3 to learn how to resolve the merge conflicts.**
Force push to your fork's dev branch to your forked repository. _Make sure all conflicts are resolved before running this command._
```
git push my dev --force
git push my dev --force
```
### 2. Rebase your working branch
@@ -214,7 +214,7 @@ git rebase my/dev # This will rebase your working branch from
### 3. Resolve merge conflicts
If you get a message saying something like below, then you have merge conflicts that must be manually resolved.
Below there is a conflict between the dev branch and your pull request branch for the file `README.md`.
Below there is a conflict between the dev branch and your pull request branch for the file `README.md`.
You can read more about how to resolve a merge conflict on the [GitHub help page](https://help.github.com/articles/resolving-a-merge-conflict-from-the-command-line/).
```
@@ -223,8 +223,8 @@ CONFLICT (content): Merge conflict in README.md
error: Failed to merge in the changes.
```
To fix this you need to manually open the file in an editor of your choosing and find the conflict. You find the conflict by searching for seven equals sign: `=======`.
Below is an example of how it could look like.
To fix this you need to manually open the file in an editor of your choosing and find the conflict. You find the conflict by searching for seven equals sign: `=======`.
Below is an example of how it could look like.
```
...
@@ -233,7 +233,7 @@ Below is an example of how it could look like.
* Added tests for resources
- xSQLServerPermission
* Fixes in xSQLServerAvailabilityGroupListener
- In one case the Get-method did not report that DHCP was configured.
- In one case the Get-method did not report that DHCP was configured.
=======
* Added resources
- xSQLServerReplication
@@ -246,7 +246,7 @@ Below is an example of how it could look like.
* Above the equals sign `========` is what's in the `README.md` of your branch.
* Below the equals sign `========` is what's in the `README.md` of the dev branch.
To resolve this we have to manually change this section. After resolving the conflict, `README.md` looks like this:
To resolve this we have to manually change this section. After resolving the conflict, `README.md` looks like this:
_Note: You must remove the lines `<<<<<<< HEAD`, `========` and `>>>>>>> origin/dev`._
```
@@ -257,73 +257,82 @@ _Note: You must remove the lines `<<<<<<< HEAD`, `========` and `>>>>>>> origin/
* Added tests for resources
- xSQLServerPermission
* Fixes in xSQLServerAvailabilityGroupListener
- In one case the Get-method did not report that DHCP was configured.
- In one case the Get-method did not report that DHCP was configured.
### 1.8.0.0
...
```
When you are happy with the file, save it and continue with the next file, if there was more merge conflicts. **Only when all the merge conflicts are resolved can you continue with the rebase.**
* To continue with the rebase. In the same PowerShell prompt as you started the rebase, you need to do the following.
* To continue with the rebase. In the same PowerShell prompt as you started the rebase, you need to do the following.
_Note: If not using the same PowerShell prompt, make sure you are in the right folder and on the right branch._
```
git status # (optional) If you unsure of the name, you can use this to see the files that was in conflict.
git add <file> # Do this for each file that you fixed merged conflicts in. I.e 'git add README.md'. This stages the file for commit. You could also use 'git add *' to stage all files at once.
git rebase --continue
```
**You can now get more merge conflicts.** If so, then you have to resolve those again. Do the same procedure as before for these new conflicts. **You might need to do this step several times.**
**You can now get more merge conflicts.** If so, then you have to resolve those again. Do the same procedure as before for these new conflicts. **You might need to do this step several times.**
Continue to step 4 only when you no longer have any merge conflicts you need to resolve (and no longer need to run the command `rebase --continue`).
### 4. Update your pull request
Force push to your branch in your forked repository. The pull request will then be updated automatically by GitHub.
```
git push my <pull request branch> --force # I.e git push my awesome_feature --force
git push my <pull request branch> --force # I.e git push my awesome_feature --force
```
## Delete a branch
Once your changes have been successfully merged into the hub repository you can delete the branch you used, as you will no longer need it.
Any further work requires a new branch.
Once your changes have been successfully merged into the hub repository you can delete the branch you used, as you will no longer need it.
Any further work requires a new branch.
To delete your branch follow these steps:
1. Run `git checkout master` in the command prompt. This ensures that you aren't in the branch to be deleted (which isn't allowed).
2. Next, type `git branch -d <branch name>` in the command prompt. This will delete the branch on your local machine only if it has been successfully merged to the upstream repository. (You can override this behavior with the `–D` flag, but first be sure you want to do this.)
3. Finally, type `git push my :<branch name>` in the command prompt (a space before the colon and no space after it). This will delete the branch on your GitHub fork.
3. Finally, type `git push my :<branch name>` in the command prompt (a space before the colon and no space after it). This will delete the branch on your GitHub fork.
## Using .gitignore to exclude files and/or folders
There are cases when you need to add some files and/or folders to a .gitignore file so changes are not staged for commit. One example is the folder `DSCResource.Tests` that is generated when running tests. This folder should normally not be part of any PR.
### Create a .gitgnore file
Run the following in a PowerShell prompt. This will add a .gitignore file to the current folder.
```
@(
```powershell
@(
".gitignore", # Excludes the .gitignore file itself
"DSCResource.Tests", # Excludes the folder that is generated when running tests
".vs", # Excludes Visual Studio settings folder
".vscode" # Excludes Visual Studio Code settings folder
) | Out-File -LiteralPath '.gitignore' -Encoding utf8 -Force
) | Out-File -LiteralPath '.gitignore' -Encoding utf8 -Force
```
Make sure this `.gitignore` file is placed in the root of your cloned repository.
## How to continue working on a pull request when an author (contributor) is unable to complete it
If the original contributor is unable to continue the work on a pull request, or if the pull request is abandoned for a long time, then there is a possibility for you to continue the work.
You can do so by getting the changes from the original contributors branch to a new working branch in your fork. Once you have create a new working branch with the original contributors changes,
then you can create a new pull request into the original repository.
It's important that when you create a new pull request from someone else's work, that you mention the original pull request, and also acknowledge the original author and mention the work it is based on.
## How to continue working on a pull request (PR) when an author (contributor) is unable to complete it
Anyone in the community is allowed to continue the work on pull requests (PR's) if either of these are true.
- If the original contributor is unable to continue the work on a pull request _and_ the original author signed the CLA.
- If the pull request have been labeled with the *abandoned* label (which also implies that the CLA was signed - otherwise the abandoned label should not have been set).
It is polite to tell the original author of the PR that you will be continuing the
work, by commenting on the original PR.
You can continue the work by getting the changes from the original contributors branch to a new working branch in your fork. Once you have create a new working branch with the original contributors changes,
then you can create a new pull request into the original repository.
It's important that when you create a new pull request from someone elses work, that you mention the original pull request, and also acknowledge the original author and mention the work it is based on.
For example mention the original author in the descriptive field when you create the new pull request.
So, to continue working on a pull request, this is done by rebasing the changes in the original pull request branch onto your new working branch. This is pretty much the same as when you have to resolve merge conflicts.
So, to continue working on a pull request, first you should rebase the changes in the original pull request branch onto your new working branch. This is pretty much the same as when you have to resolve merge conflicts.
* In a PowerShell prompt, you need to do the following.
1. Create a new working branch in your fork.
```
cd <path to cloned repository>
cd <path to cloned repository>
git checkout -b changes-from-PR#<number> # Change to the number of the PR you are taking over. I.e. git checkout -b changes-from-PR#34
```
@@ -347,11 +356,11 @@ So, to continue working on a pull request, this is done by rebasing the changes
git rebase --continue
```
5. Push changes to your forked repository
5. Push changes to your forked repository
```
git push my changes-from-PR#<number> --force # Change to the number of the PR you are taking over. You have to use --force. I.e. git push my changes-from-PR#34 --force
```
```
6. Now we rebase again, this time against my/dev (which should already be rebased against origin/dev, see section Resolving merge conflicts on how to do that).
Oops, something went wrong.

0 comments on commit 4834310

Please sign in to comment.