Skip to content
This repository was archived by the owner on Dec 8, 2021. It is now read-only.

Commit 54346b4

Browse files
Tiberriver256Tiberriver256
authored
New about guides (#164)
* Updated appveyor to exclude other docs changes * Filled in Polaris URL in GitHub guidance where applicable * Removed references to the wiki * Added a couple of about files to help getting started * Addition tip for peeps who don't want to touch vim * Update docs/about_GettingStarted.md Co-Authored-By: Tiberriver256 <Micah.rairdon@gmail.com> * Update docs/about_GettingStarted.md Co-Authored-By: Tiberriver256 <Micah.rairdon@gmail.com> * Update docs/about_GettingStarted.md Co-Authored-By: Tiberriver256 <Micah.rairdon@gmail.com> * Update docs/about_GettingStarted.md Co-Authored-By: Tiberriver256 <Micah.rairdon@gmail.com> * Update docs/about_GettingStarted.md Co-Authored-By: Tiberriver256 <Micah.rairdon@gmail.com> * Apply suggestions from code review Co-Authored-By: Tiberriver256 <Micah.rairdon@gmail.com> * Removing prettier's crazy extra spacing * Removing one more extra space * Update docs/about_GettingStarted.md Co-Authored-By: Tiberriver256 <Micah.rairdon@gmail.com> * Few more touchups * Update docs/about_GettingStarted.md Co-Authored-By: Tiberriver256 <Micah.rairdon@gmail.com> * Update docs/about_GettingStarted.md Co-Authored-By: Tiberriver256 <Micah.rairdon@gmail.com>
1 parent f62d99c commit 54346b4

File tree

5 files changed

+371
-124
lines changed

5 files changed

+371
-124
lines changed

‎GITHUB_GUIDANCE.md‎

Lines changed: 116 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -1,106 +1,116 @@
1-
# Some helpful guidance for Github / git newbies
2-
3-
A large chunk taken from [this beautiful gist](https://gist.github.com/Chaser324/ce0505fbed06b947d962) from @Chaser324
4-
5-
Whether you're trying to give back to the open source community or collaborating on your own projects, knowing how to properly fork and generate pull requests is essential. Unfortunately, it's quite easy to make mistakes or not know what you should do when you're initially learning the process. I know that I certainly had considerable initial trouble with it, and I found a lot of the information on GitHub and around the internet to be rather piecemeal and incomplete - part of the process described here, another there, common hangups in a different place, and so on.
6-
7-
In an attempt to coallate this information for myself and others, this short tutorial is what I've found to be fairly standard procedure for creating a fork, doing your work, issuing a pull request, and merging that pull request back into the original project.
8-
9-
## Creating a Fork
10-
11-
Just head over to the GitHub page and click the "Fork" button. It's just that simple. Once you've done that, you can use your favorite git client to clone your repo or just head straight to the command line:
12-
13-
```shell
14-
# Clone your fork to your local machine
15-
git clone git@github.com:USERNAME/FORKED-PROJECT.git
16-
```
17-
18-
## Keeping Your Fork Up to Date
19-
20-
While this isn't an absolutely necessary step, if you plan on doing anything more than just a tiny quick fix, you'll want to make sure you keep your fork up to date by tracking the original "upstream" repo that you forked. To do this, you'll need to add a remote:
21-
22-
```shell
23-
# Add 'upstream' repo to list of remotes
24-
git remote add upstream https://github.com/UPSTREAM-USER/ORIGINAL-PROJECT.git
25-
26-
# Verify the new remote named 'upstream'
27-
git remote -v
28-
```
29-
30-
Whenever you want to update your fork with the latest upstream changes, you'll need to first fetch the upstream repo's branches and latest commits to bring them into your repository:
31-
32-
```shell
33-
# Fetch from upstream remote
34-
git fetch upstream
35-
36-
# View all branches, including those from upstream
37-
git branch -va
38-
```
39-
40-
Now, checkout your own master branch and merge the upstream repo's master branch:
41-
42-
```shell
43-
# Checkout your master branch and merge upstream
44-
git checkout master
45-
git merge upstream/master
46-
```
47-
48-
If there are no unique commits on the local master branch, git will simply perform a fast-forward. However, if you have been making changes on master (in the vast majority of cases you probably shouldn't be - [see the next section](#doing-your-work), you may have to deal with conflicts. When doing so, be careful to respect the changes made upstream.
49-
50-
Now, your local master branch is up-to-date with everything modified upstream.
51-
52-
## Doing Your Work
53-
54-
### Create a Branch
55-
56-
Whenever you begin work on a new feature or bugfix, it's important that you create a new branch. Not only is it proper git workflow, but it also keeps your changes organized and separated from the master branch so that you can easily submit and manage multiple pull requests for every task you complete.
57-
58-
To create a new branch and start working on it:
59-
60-
```shell
61-
# Checkout the master branch - you want your new branch to come from master
62-
git checkout master
63-
64-
# Create a new branch named newfeature (give your branch its own simple informative name)
65-
git branch newfeature
66-
67-
# Switch to your new branch
68-
git checkout newfeature
69-
```
70-
71-
Now, go to town hacking away and making whatever changes you want to.
72-
73-
## Submitting a Pull Request
74-
75-
### Cleaning Up Your Work
76-
77-
Prior to submitting your pull request, you might want to do a few things to clean up your branch and make it as simple as possible for the original repo's maintainer to test, accept, and merge your work.
78-
79-
If any commits have been made to the upstream master branch, you should rebase your development branch so that merging it will be a simple fast-forward that won't require any conflict resolution work.
80-
81-
```shell
82-
# Fetch upstream master and merge with your repo's master branch
83-
git fetch upstream
84-
git checkout master
85-
git merge upstream/master
86-
87-
# If there were any new commits, rebase your development branch
88-
git checkout newfeature
89-
git rebase master
90-
```
91-
92-
Now, it may be desirable to squash some of your smaller commits down into a small number of larger more cohesive commits. You can do this with an interactive rebase:
93-
94-
```shell
95-
# Rebase all commits on your development branch
96-
git checkout
97-
git rebase -i master
98-
```
99-
100-
This will open up a text editor where you can specify which commits to squash.
101-
102-
### Recommended git / github learning resources
103-
104-
Github Learning Lab - [https://lab.github.com/](https://lab.github.com/)
105-
Interactive Git Branching Tutorial - [https://learngitbranching.js.org/](https://learngitbranching.js.org/)
106-
Additional resources - [https://try.github.io/](https://try.github.io/)
1+
# Some helpful guidance for Github / git newbies
2+
3+
A large chunk taken from [this beautiful gist](https://gist.github.com/Chaser324/ce0505fbed06b947d962) from @Chaser324
4+
5+
Whether you're trying to give back to the open source community or collaborating on your own projects, knowing how to properly fork and generate pull requests is essential. Unfortunately, it's quite easy to make mistakes or not know what you should do when you're initially learning the process. I know that I certainly had considerable initial trouble with it, and I found a lot of the information on GitHub and around the internet to be rather piecemeal and incomplete - part of the process described here, another there, common hangups in a different place, and so on.
6+
7+
In an attempt to coallate this information for myself and others, this short tutorial is what I've found to be fairly standard procedure for creating a fork, doing your work, issuing a pull request, and merging that pull request back into the original project.
8+
9+
## Use VSCode for Git
10+
11+
The default editor (which you may not run into very often) is vim. If you're more familiar with VSCode you and set VSCode to be the default editor for interactive commands like `git rebase -i` using the following command:
12+
13+
```
14+
git config --global core.editor "code --wait"
15+
```
16+
17+
More information [here](https://code.visualstudio.com/docs/editor/versioncontrol#_vs-code-as-git-editor)
18+
19+
## Creating a Fork
20+
21+
Just head over to the GitHub page and click the "Fork" button. It's just that simple. Once you've done that, you can use your favorite git client to clone your repo or just head straight to the command line:
22+
23+
```shell
24+
# Clone your fork to your local machine
25+
git clone git@github.com:USERNAME/Polaris.git
26+
```
27+
28+
## Keeping Your Fork Up to Date
29+
30+
While this isn't an absolutely necessary step, if you plan on doing anything more than just a tiny quick fix, you'll want to make sure you keep your fork up to date by tracking the original "upstream" repo that you forked. To do this, you'll need to add a remote:
31+
32+
```shell
33+
# Add 'upstream' repo to list of remotes
34+
git remote add upstream https://github.com/PowerShell/Polaris.git
35+
36+
# Verify the new remote named 'upstream'
37+
git remote -v
38+
```
39+
40+
Whenever you want to update your fork with the latest upstream changes, you'll need to first fetch the upstream repo's branches and latest commits to bring them into your repository:
41+
42+
```shell
43+
# Fetch from upstream remote
44+
git fetch upstream
45+
46+
# View all branches, including those from upstream
47+
git branch -va
48+
```
49+
50+
Now, checkout your own master branch and merge the upstream repo's master branch:
51+
52+
```shell
53+
# Checkout your master branch and merge upstream
54+
git checkout master
55+
git merge upstream/master
56+
```
57+
58+
If there are no unique commits on the local master branch, git will simply perform a fast-forward. However, if you have been making changes on master (in the vast majority of cases you probably shouldn't be - [see the next section](#doing-your-work), you may have to deal with conflicts. When doing so, be careful to respect the changes made upstream.
59+
60+
Now, your local master branch is up-to-date with everything modified upstream.
61+
62+
## Doing Your Work
63+
64+
### Create a Branch
65+
66+
Whenever you begin work on a new feature or bugfix, it's important that you create a new branch. Not only is it proper git workflow, but it also keeps your changes organized and separated from the master branch so that you can easily submit and manage multiple pull requests for every task you complete.
67+
68+
To create a new branch and start working on it:
69+
70+
```shell
71+
# Checkout the master branch - you want your new branch to come from master
72+
git checkout master
73+
74+
# Create a new branch named newfeature (give your branch its own simple informative name)
75+
git branch newfeature
76+
77+
# Switch to your new branch
78+
git checkout newfeature
79+
```
80+
81+
Now, go to town hacking away and making whatever changes you want to.
82+
83+
## Submitting a Pull Request
84+
85+
### Cleaning Up Your Work
86+
87+
Prior to submitting your pull request, you might want to do a few things to clean up your branch and make it as simple as possible for the original repo's maintainer to test, accept, and merge your work.
88+
89+
If any commits have been made to the upstream master branch, you should rebase your development branch so that merging it will be a simple fast-forward that won't require any conflict resolution work.
90+
91+
```shell
92+
# Fetch upstream master and merge with your repo's master branch
93+
git fetch upstream
94+
git checkout master
95+
git merge upstream/master
96+
97+
# If there were any new commits, rebase your development branch
98+
git checkout newfeature
99+
git rebase master
100+
```
101+
102+
Now, it may be desirable to squash some of your smaller commits down into a small number of larger more cohesive commits. You can do this with an interactive rebase:
103+
104+
```shell
105+
# Rebase all commits on your development branch
106+
git checkout
107+
git rebase -i master
108+
```
109+
110+
This will open up a text editor where you can specify which commits to squash.
111+
112+
### Recommended git / github learning resources
113+
114+
Github Learning Lab - [https://lab.github.com/](https://lab.github.com/)
115+
Interactive Git Branching Tutorial - [https://learngitbranching.js.org/](https://learngitbranching.js.org/)
116+
Additional resources - [https://try.github.io/](https://try.github.io/)

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,21 +42,21 @@ Polaris' differentiation is that it is cross-platform and uses the .NET HttpList
4242
PS > Install-Module Polaris
4343
```
4444

45-
You can now try out the [example above](#example) or checkout [the wiki](https://github.com/PowerShell/Polaris/wiki) for more usage!
45+
You can now try out the [example above](#example) or checkout [the site](https://PowerShell.github.io/Polaris) for more usage information!
4646

4747
#### From source
4848

4949
1. Clone or download the zip of the repo
5050
1. Open [PowerShell](https://github.com/powershell/powershell)
5151
1. At this point, you can now run `Import-Module ./Polaris.psd1`
5252

53-
You can now try out the [example above](#example) or checkout [the wiki](https://github.com/PowerShell/Polaris/wiki) for more usage!
53+
You can now try out the [example above](#example) or checkout [the site](https://PowerShell.github.io/Polaris) for more usage!
5454

5555
You can also run all the Pester tests by running `Invoke-Pester` in the `test` directory. You will need [Pester](https://github.com/pester/Pester) version [4.1.0](https://github.com/pester/Pester/blob/master/CHANGELOG.md#410-november-15-2017) or higher to run the tests on Linux or MacOS.
5656

5757
## Documentation
5858

59-
Check out the [docs folder](https://github.com/PowerShell/Polaris/tree/master/docs) for the API reference.
59+
Check out the [docs folder](https://github.com/PowerShell/Polaris/tree/master/docs) or [the site](https://PowerShell.github.io/Polaris) for a full API reference.
6060

6161
## Troubleshooting / Questions
6262

‎appveyor.yml‎

Lines changed: 20 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
image:
2-
- Visual Studio 2015
3-
- Ubuntu
2+
- Visual Studio 2015
3+
- Ubuntu
44

55
build: off
66

@@ -10,32 +10,37 @@ version: 0.0.1.{build}
1010
# Ignore testing a commit if only the README.md file changed
1111
# Or if various strings are found in the commit message: updated readme, update readme, update docs, update version, update appveyor
1212
skip_commits:
13-
files:
14-
- README.md
15-
message: /updated readme.*|update readme.*s|update docs.*|update version.*|update appveyor.*/
13+
files:
14+
- README.md
15+
- CONTRIBUTING.md
16+
- GITHUB_GUIDANCE.md
17+
- docs/*
18+
- .github/*
19+
- .vscode/*
20+
message: /updated readme.*|update readme.*s|update docs.*|update version.*|update appveyor.*/
1621

1722
branches:
18-
only:
19-
- master
23+
only:
24+
- master
2025

2126
# There's no need to alter the build number for a Pull Request (PR) since they don't modify anything
2227
pull_requests:
23-
do_not_increment_build_number: true
28+
do_not_increment_build_number: true
2429

2530
# Install NuGet to interact with the PowerShell Gallery
2631
install:
27-
- ps: Install-Module Pester -Scope CurrentUser -Force
32+
- ps: Install-Module Pester -Scope CurrentUser -Force
2833

2934
# Invoke Pester to run all of the unit tests, then save the results into XML in order to populate the AppVeyor tests section
3035
# If any of the tests fail, consider the pipeline failed
3136
test_script:
32-
- ps: ./build.ps1 -Test -Package
33-
- pwsh: ./build.ps1 -Test -Package
37+
- ps: ./build.ps1 -Test -Package
38+
- pwsh: ./build.ps1 -Test -Package
3439

3540
artifacts:
36-
- path: out\Polaris
37-
name: Polaris
41+
- path: out\Polaris
42+
name: Polaris
3843

3944
notifications:
40-
- provider: Webhook
41-
url: https://webhooks.gitter.im/e/7df8f5e3e64fdfe09739
45+
- provider: Webhook
46+
url: https://webhooks.gitter.im/e/7df8f5e3e64fdfe09739

0 commit comments

Comments
 (0)