Skip to content

Commit 25c5fac

Browse files
gep13gep13
committed
(doc) Markdown lint fixes
1 parent 581de4a commit 25c5fac

23 files changed

+376
-134
lines changed

‎.vscode/settings.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
{
2+
"editor.rulers": [80],
23
"cSpell.words": [
34
"addasset",
45
"buildartifacts",

‎docs/input/docs/advanced.md

Lines changed: 62 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -3,26 +3,38 @@ Order: 20
33
Title: Advanced Workflow
44
---
55

6-
In order to best understand the use case for GitReleaseManager let's take a look at an example workflow currently in use by the Chocolatey GUI project.
6+
In order to best understand the use case for GitReleaseManager let's take a look
7+
at an example workflow currently in use by the Chocolatey GUI project.
78

89
:::{.alert .alert-info}
9-
Chocolatey GUI uses a number of concepts, for example, GitFlow, psake build script engine, AppVeyor Continuous Integration, as well as using GitReleaseManager. In order to understand the usage of GitReleaseManager for this project, you sort of have to understand the entire process. As a result, this walk-through steps you through the entire end to end process, which as a result, means it is quite lengthy.
10+
Chocolatey GUI uses a number of concepts, for example, GitFlow, psake build
11+
script engine, AppVeyor Continuous Integration, as well as using
12+
GitReleaseManager. In order to understand the usage of GitReleaseManager for
13+
this project, you sort of have to understand the entire process. As a result,
14+
this walk-through steps you through the entire end to end process, which as a
15+
result, means it is quite lengthy.
1016
:::
1117

1218
## Chocolatey GUI
1319

14-
[Chocolatey GUI](https://github.com/chocolatey/ChocolateyGUI) is an open source project, hosted on GitHub that makes use of GitReleaseManager to create and export it's release notes. Before we can get into how GitReleaseManager is used, we need to take a look at how Chocolatey GUI is setup.
20+
[Chocolatey GUI](https://github.com/chocolatey/ChocolateyGUI) is an open source
21+
project, hosted on GitHub that makes use of GitReleaseManager to create and
22+
export it's release notes. Before we can get into how GitReleaseManager is
23+
used, we need to take a look at how Chocolatey GUI is setup.
1524

1625
### GitHub Setup
1726

18-
* All Issues are tracked using the[ GitHub Issues List](https://github.com/chocolatey/ChocolateyGUI/issues)
27+
* All Issues are tracked using the [GitHub Issues List](https://github.com/chocolatey/ChocolateyGUI/issues)
1928
* Each Issue is assigned to a [project milestone](https://github.com/chocolatey/ChocolateyGUI/milestones)
2029
* Each Issue is appropriately tagged using one of the [pre-defined labels](https://github.com/chocolatey/ChocolateyGUI/labels)
2130

2231
### GitFlow
2332

2433
* Chocolatey GUI uses the [GitFlow Branching Model](http://nvie.com/posts/a-successful-git-branching-model/)
25-
* [GitVersion](https://github.com/ParticularLabs/GitVersion) is used to determine the current version number, based on the current state of the repository, i.e. what branch is being worked on, and what tags have been assigned, and how many commits have been made to the repository
34+
* [GitVersion](https://github.com/ParticularLabs/GitVersion) is used to
35+
determine the current version number, based on the current state of the
36+
repository, i.e. what branch is being worked on, and what tags have been
37+
assigned, and how many commits have been made to the repository
2638

2739
### Build Artifacts
2840

@@ -34,34 +46,63 @@ Every build of Chocolatey GUI generates a number of Build Artifacts, these inclu
3446
### Continuous Integration
3547

3648
* Chocolatey GUI uses [AppVeyor](http://www.appveyor.com/) as it's Continuous Integration Server.
37-
* Any time a **Pull Request** is created, an AppVeyor build is triggered, but no deployment of the build artifacts takes place
38-
* Any time a commit is made into the **develop **branch, an AppVeyor build is triggered, and the build artifacts are deployed to the [MyGet Develop Feed](https://www.myget.org/feed/Packages/ghrm_develop)
39-
* Any time a commit is made into the **master **branch, an AppVeyor build is triggered, and the build artifacts are deployed to the [MyGet Master Feed](https://www.myget.org/feed/Packages/ghrm_master)
40-
* Any time a **tag **is applied to the repository, an AppVeyor build is triggered, and the build artifacts are deployed to [Chocolatey.org](https://chocolatey.org/) for public consumption.
49+
* Any time a **Pull Request** is created, an AppVeyor build is triggered, but no
50+
deployment of the build artifacts takes place
51+
* Any time a commit is made into the **develop **branch, an AppVeyor build is
52+
triggered, and the build artifacts are deployed to the
53+
[MyGet Develop Feed](https://www.myget.org/feed/Packages/ghrm_develop)
54+
* Any time a commit is made into the **master **branch, an AppVeyor build is
55+
triggered, and the build artifacts are deployed to the
56+
[MyGet Master Feed](https://www.myget.org/feed/Packages/ghrm_master)
57+
* Any time a **tag **is applied to the repository, an AppVeyor build is
58+
triggered, and the build artifacts are deployed to
59+
[Chocolatey.org](https://chocolatey.org/) for public consumption.
4160

4261
### Ok, so where does GitReleaseManager come into play?
4362

44-
The role of GitReleaseManager really comes into play when moving between a **release** or **hotfix** branch and the **master **branch.
63+
The role of GitReleaseManager really comes into play when moving between a
64+
**release** or **hotfix** branch and the **master **branch.
4565

46-
Let's say you have done a bunch of work on the develop branch, you want to move all of that work into the master branch, via a release branch. When you do this, you are effectively saying that the milestone that you were working on is almost ready for release. It is at this point that you should really know, via the issues list, everything that is being included in the release, and now would seem like a great time to create some release notes. And this is exactly what the build process for Chocolatey GUI does. Let's break this down further...
66+
Let's say you have done a bunch of work on the develop branch, you want to move
67+
all of that work into the master branch, via a release branch. When you do
68+
this, you are effectively saying that the milestone that you were working on is
69+
almost ready for release. It is at this point that you should really know, via
70+
the issues list, everything that is being included in the release, and now would
71+
seem like a great time to create some release notes. And this is exactly what
72+
the build process for Chocolatey GUI does. Let's break this down further...
4773

4874
* A **release **branch is created from **develop **branch
49-
* The release branch is merged into master branch, triggering a build (with deployment to MyGet Master Feed).
50-
* During this build, GitReleaseManager is executed, using the **create** command, and the version number which was provided by GitVersion, to create a set of release notes for this milestone - [source](https://github.com/chocolatey/ChocolateyGUI/blob/09b78495ebc9d334fedf351b021fd7e215c5cf87/BuildScripts/default.ps1#L687).
51-
* This set of release notes is created in draft format, ready for review, in the GitHub UI.
75+
* The release branch is merged into master branch, triggering a build (with
76+
deployment to MyGet Master Feed).
77+
* During this build, GitReleaseManager is executed, using the **create**
78+
command, and the version number which was provided by GitVersion, to create a
79+
set of release notes for this milestone - [source](https://github.com/chocolatey/ChocolateyGUI/blob/09b78495ebc9d334fedf351b021fd7e215c5cf87/BuildScripts/default.ps1#L687).
80+
* This set of release notes is created in draft format, ready for review, in the
81+
GitHub UI.
5282
* The build artifacts which have been deployed to MyGet Master Feed are tested
5383
* The release notes are reviewed, and ensured to be correct
54-
* Assuming that everything is verified to be correct, the draft release is then published through the GitHub UI, which creates a tag in the repository, triggering another AppVeyor build, this time with deployment to Chocolatey.org
55-
* During this build, GitReleaseManager is executed using the **export** command, so that all release notes can be bundled into the application - [source](https://github.com/chocolatey/ChocolateyGUI/blob/09b78495ebc9d334fedf351b021fd7e215c5cf87/BuildScripts/default.ps1#L707)
56-
* In addition, GitReleaseManager is executed using the **addasset** command to add the build artifacts to the GitHub release - [source](https://github.com/chocolatey/ChocolateyGUI/blob/09b78495ebc9d334fedf351b021fd7e215c5cf87/BuildScripts/default.ps1#L731)
57-
* And finally, GitReleaseManager is executed using the **close** command to close the milestone associated with the release that has just been published - [source](https://github.com/chocolatey/ChocolateyGUI/blob/09b78495ebc9d334fedf351b021fd7e215c5cf87/BuildScripts/default.ps1#L753)
58-
59-
The end result of this process can be seen [here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.12.0). This release included 218 commits, and 75 issues. Personally, I simply wouldn't have created such a comprehensive set of release notes manually. Instead, I would have written something like...
84+
* Assuming that everything is verified to be correct, the draft release is then
85+
published through the GitHub UI, which creates a tag in the repository,
86+
triggering another AppVeyor build, this time with deployment to Chocolatey.org
87+
* During this build, GitReleaseManager is executed using the **export** command,
88+
so that all release notes can be bundled into the application - [source](https://github.com/chocolatey/ChocolateyGUI/blob/09b78495ebc9d334fedf351b021fd7e215c5cf87/BuildScripts/default.ps1#L707)
89+
* In addition, GitReleaseManager is executed using the **addasset** command to
90+
add the build artifacts to the GitHub release - [source](https://github.com/chocolatey/ChocolateyGUI/blob/09b78495ebc9d334fedf351b021fd7e215c5cf87/BuildScripts/default.ps1#L731)
91+
* And finally, GitReleaseManager is executed using the **close** command to
92+
close the milestone associated with the release that has just been published - [source](https://github.com/chocolatey/ChocolateyGUI/blob/09b78495ebc9d334fedf351b021fd7e215c5cf87/BuildScripts/default.ps1#L753)
93+
94+
The end result of this process can be seen
95+
[here](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.12.0).
96+
This release included 218 commits, and 75 issues. Personally, I simply wouldn't
97+
have created such a comprehensive set of release notes manually. Instead, I
98+
would have written something like...
6099

61100
```text
62101
#0.12.0
63102
64103
This release included lots of bug fixes, and tonnes of new features. Enjoy!
65104
```
66105

67-
By leveraging GitVersion, and GitReleaseManager, and a small amount of process (which you are likely already doing), I hope you will agree that you can very easily create a comprehensive set of release notes for your application.
106+
By leveraging GitVersion, and GitReleaseManager, and a small amount of process
107+
(which you are likely already doing), I hope you will agree that you can very
108+
easily create a comprehensive set of release notes for your application.

‎docs/input/docs/commands/add-assets.md

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,30 @@ Order: 20
33
Title: Add Assets
44
---
55

6-
Once a draft set of release notes has been created, it is possible to add additional assets to the release using the addasset command.
6+
Once a draft set of release notes has been created, it is possible to add
7+
additional assets to the release using the addasset command.
78

89
## **Required Parameters**
910

10-
* `-u, --username`: The username to access GitHub with. This can't be used when using the token parameter.
11-
* `-p, --password`: The password to access GitHub with. This can't be used when using the token parameter.
12-
* `--token`: The access token to access GitHub with. This can't be used when using the username and password parameters.
11+
* `-u, --username`: The username to access GitHub with. This can't be used when
12+
using the token parameter.
13+
* `-p, --password`: The password to access GitHub with. This can't be used when
14+
using the token parameter.
15+
* `--token`: The access token to access GitHub with. This can't be used when
16+
using the username and password parameters.
1317
* `-o, --owner`: The owner of the repository.
1418
* `-r, --repository`: The name of the repository.
15-
* `-t, --tagName`: The name of the release (Typically this is the generated SemVer Version Number).
16-
* `-a, --assets`: Path(s) to the file(s) to include in the release. This is a comma separated list of files to include
19+
* `-t, --tagName`: The name of the release (Typically this is the generated
20+
SemVer Version Number).
21+
* `-a, --assets`: Path(s) to the file(s) to include in the release. This is a
22+
comma separated list of files to include
1723

1824
## **Optional Parameters**
1925

20-
* `-d, -targetDirectory`: The directory on which GitReleaseManager should be executed. Defaults to current directory.
21-
* `-l, -logFilePath`: Path to where log file should be created. Defaults to logging to console.
26+
* `-d, -targetDirectory`: The directory on which GitReleaseManager should be
27+
executed. Defaults to current directory.
28+
* `-l, -logFilePath`: Path to where log file should be created. Defaults to
29+
logging to console.
2230

2331
## **Notes**
2432

‎docs/input/docs/commands/close.md

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,21 +3,28 @@ Order: 40
33
Title: Close
44
---
55

6-
Out of the box, publishing a release on GitHub does not close the milestone associated with the release. This command, when executed, closes the specified milestone.
6+
Out of the box, publishing a release on GitHub does not close the milestone
7+
associated with the release. This command, when executed, closes the specified
8+
milestone.
79

810
## **Required Parameters**
911

10-
* `-u, --username`: The username to access GitHub with. This can't be used when using the token parameter.
11-
* `-p, --password`: The password to access GitHub with. This can't be used when using the token parameter.
12-
* `--token`: The access token to access GitHub with. This can't be used when using the username and password parameters.
12+
* `-u, --username`: The username to access GitHub with. This can't be used when
13+
using the token parameter.
14+
* `-p, --password`: The password to access GitHub with. This can't be used when
15+
using the token parameter.
16+
* `--token`: The access token to access GitHub with. This can't be used when
17+
using the username and password parameters.
1318
* `-o, --owner`: The owner of the repository.
1419
* `-r, --repository`: The name of the repository.
1520
* `-m, --milestone`: The milestone to use.
1621

1722
## **Optional Parameters**
1823

19-
* `-d, --targetDirectory`: The directory on which GitReleaseManager should be executed. Defaults to current directory.
20-
* `-l, --logFilePath`: Path to where log file should be created. Defaults to logging to console.
24+
* `-d, --targetDirectory`: The directory on which GitReleaseManager should be
25+
executed. Defaults to current directory.
26+
* `-l, --logFilePath`: Path to where log file should be created. Defaults to
27+
logging to console.
2128

2229
## **Notes**
2330

‎docs/input/docs/commands/create.md

Lines changed: 26 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,36 +3,50 @@ Order: 10
33
Title: Create
44
---
55

6-
This is the main command of GitReleaseManager and it is used to create a draft set of release notes based on a milestone, which has been set up in GitHub.
6+
This is the main command of GitReleaseManager and it is used to create a draft
7+
set of release notes based on a milestone, which has been set up in GitHub.
78

8-
There are two modes of operation when creating a Release. GitReleaseManager can take as an input the name of the milestone to generate the release notes from. Or, it can take as an input the name of a file which contains the release notes to include in the Release.
9+
There are two modes of operation when creating a Release. GitReleaseManager can
10+
take as an input the name of the milestone to generate the release notes from.
11+
Or, it can take as an input the name of a file which contains the release notes
12+
to include in the Release.
913

1014
## **Required Parameters**
1115

12-
* `-u, --username`: The username to access GitHub with. This can't be used when using the token parameter.
13-
* `-p, --password`: The password to access GitHub with. This can't be used when using the token parameter.
14-
* `--token`: The access token to access GitHub with. This can't be used when using the username and password parameters.
16+
* `-u, --username`: The username to access GitHub with. This can't be used when
17+
using the token parameter.
18+
* `-p, --password`: The password to access GitHub with. This can't be used when
19+
using the token parameter.
20+
* `--token`: The access token to access GitHub with. This can't be used when
21+
using the username and password parameters.
1522
* `-o, --owner`: The owner of the repository.
1623
* `-r, --repository`: The name of the repository.
1724

1825
## **Optional Parameters**
1926

2027
* `-m, --milestone`: The milestone to use.
21-
* `-n, --name`: The name of the release (Typically this is the generated SemVer Version Number).
22-
* `-i, --inputFilePath`: The path to the file to be used as the content of the release notes.
28+
* `-n, --name`: The name of the release (Typically this is the generated SemVer
29+
Version Number).
30+
* `-i, --inputFilePath`: The path to the file to be used as the content of the
31+
release notes.
2332
* `-e, --pre`: Creates the release as a pre-release.
24-
* `-a, --assets`: Path(s) to the file(s) to include in the release. This is a comma separated list of files to include
25-
* `-c, --targetcommitish`: The commit to tag. Can be a branch or SHA. Defaults to repository's default branch.
26-
* `-d, --targetDirectory`: The directory on which GitReleaseManager should be executed. Defaults to current directory.
27-
* `-l, --logFilePath`: Path to where log file should be created. Defaults to logging to console.
33+
* `-a, --assets`: Path(s) to the file(s) to include in the release. This is a
34+
comma separated list of files to include
35+
* `-c, --targetcommitish`: The commit to tag. Can be a branch or SHA. Defaults
36+
to repository's default branch.
37+
* `-d, --targetDirectory`: The directory on which GitReleaseManager should be
38+
executed. Defaults to current directory.
39+
* `-l, --logFilePath`: Path to where log file should be created. Defaults to
40+
logging to console.
2841

2942
## **Notes**
3043

3144
For Authentication use either username and password, or token parameter
3245

3346
## **Examples**
3447

35-
Use GitReleaseManager to create a Release, generating the release notes based on Milestone:
48+
Use GitReleaseManager to create a Release, generating the release notes based on
49+
Milestone:
3650

3751
```bash
3852
gitreleasemanager.exe create -m 0.1.0 -u bob -p password -o repoOwner -r repo

0 commit comments

Comments
 (0)