(doc) First pass at porting docs from readme.io

Author: gep13

docs/advanced.md

@@ -0,0 +1,62 @@
+# Advanced Workflow
+
+In order to best understand the use case for GitReleaseManager let's take a look at an example workflow currently in use by the ChocolateyGUI project.
+
+<div class="admonition note">
+    <p class="first admonition-title">Note</p>
+    <p class="last">
+        ChocolateyGUI 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.
+    </p>
+</div>
+
+# ChocolateyGUI 
+[ChocolateyGUI](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 ChocolateyGUI is setup.
+
+## GitHub Setup 
+  * All Issues are tracked using the[ GitHub Issues List](https://github.com/chocolatey/ChocolateyGUI/issues) 
+  * Each Issue is assigned to a [project milestone](https://github.com/chocolatey/ChocolateyGUI/milestones) 
+  * Each Issue is appropriately tagged using one of the [pre-defined labels](https://github.com/chocolatey/ChocolateyGUI/labels) 
+
+## GitFlow 
+  * ChocolateyGUI uses the [GitFlow Branching Model](http://nvie.com/posts/a-successful-git-branching-model/) 
+  * [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
+
+## Build Artifacts
+Every build of ChocolateyGUI generates a number of Build Artifacts, these include:
+  * An MSI package for installing ChocolateyGUI
+  * A Chocolatey package to ease the installation of ChocolateyGUI
+
+## Continuous Integration 
+
+  * ChocolateyGUI uses [AppVeyor](http://www.appveyor.com/) as it's Continuous Integration Server. 
+  * Any time a **Pull Request** is created, an AppVeyor build is triggered, but no deployment of the build artifacts takes place
+  * 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)
+  * 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)
+  * 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.
+
+## Ok, so where does GitReleaseManager come into play?
+ 
+The role of GitReleaseManager really comes into play when moving between a **release** or **hotfix** branch and the **master **branch.  
+
+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 ChocolateyGUI does.  Let's break this down further...
+
+  * A **release **branch is created from **develop **branch 
+  * The release branch is merged into master branch, triggering a build (with deployment to MyGet Master Feed).
+  * 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).
+  * This set of release notes is created in draft format, ready for review, in the GitHub UI.
+  * The build artifacts which have been deployed to MyGet Master Feed are tested
+  * The release notes are reviewed, and ensured to be correct
+  * 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
+  * 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)
+  * 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) 
+  * 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) 
+
+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...
+
+```
+#0.12.0
+
+This release included lots of bug fixes, and tonnes of new features.  Enjoy!
+```
+
+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.

docs/commands/add-assets.md

@@ -1 +1,23 @@
-add assets
+# Add Assets
+
+Once a draft set of release notes has been created, it is possible to add additional assets to the release using the addasset command.
+
+## **Required Parameters**
+  * `-u, -username`: The username to access GitHub with.
+  * `-p, -password`: The password to access GitHub with.
+  * `-o, -owner`: The owner of the repository.
+  * `-r, -repository`: The name of the repository.
+  * `-t, -tagName`: The name of the release (Typically this is the generated SemVer Version Number).
+  * `-a, -assets`: Path(s) to the file(s) to include in the release.  This is a comma separated list of files to include
+
+## **Optional Parameters**
+  * `-d, -targetDirectory`: The directory on which GitReleaseManager should be executed. Defaults to current directory.
+  * `-l, -logFilePath`: Path to where log file should be created. Defaults to logging to console.
+
+## **Examples**
+
+```
+gitreleasemanager.exe addasset -t 0.1.0 -u bob -p password -o repoOwner -r repo -a c:\buildartifacts\setup.exe,c:\buildartifacts\setup.nupkg
+
+gitreleasemanager.exe create -tagName 0.1.0 -username bob -password password -owner repoOwner -repository repo -assets c:\buildartifacts\setup.exe,c:\buildartifacts\setup.nupkg
+```

docs/commands/close.md

@@ -1 +1,22 @@
-close
+# Close
+
+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.
+
+## **Required Parameters**
+  * `-u, -username`: The username to access GitHub with.
+  * `-p, -password`: The password to access GitHub with.
+  * `-o, -owner`: The owner of the repository.
+  * `-r, -repository`: The name of the repository.
+  * `-m, -milestone`: The milestone to use.
+
+## **Optional Parameters**
+  * `-d, -targetDirectory`: The directory on which GitReleaseManager should be executed. Defaults to current directory.
+  * `-l, -logFilePath`: Path to where log file should be created. Defaults to logging to console.
+
+## **Examples** 
+
+```
+gitreleasemanager.exe close -m 0.1.0 -u bob -p password -o repoOwner -r repo
+
+gitreleasemanager.exe close -milestone 0.1.0 -username bob -password password -owner repoOwner -repository repo
+```

docs/commands/create.md

@@ -1 +1,39 @@
-create
+# Create
+
+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.
+
+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.
+
+## **Required Parameters**
+  * `-u, -username`: The username to access GitHub with.
+  * `-p, -password`: The password to access GitHub with.
+  * `-o, -owner`: The owner of the repository.
+  * `-r, -repository`: The name of the repository.
+
+## **Optional Parameters**
+  * `-m, -milestone`: The milestone to use.
+  * `-n, -name`: The name of the release (Typically this is the generated SemVer Version Number).
+  * `-i, -inputFilePath`: The path to the file to be used as the content of the release notes.
+  * `-e, -pre`: Creates the release as a pre-release.
+  * `-a, -assets`: Path(s) to the file(s) to include in the release.  This is a comma separated list of files to include
+  * `-c, -targetcommitish`: The commit to tag. Can be a branch or SHA. Defaults to repository's default branch.
+  * `-d, -targetDirectory`: The directory on which GitReleaseManager should be executed. Defaults to current directory.
+  * `-l, -logFilePath`: Path to where log file should be created. Defaults to logging to console.
+
+## **Examples** 
+
+Use GitReleaseManager to create a Release, generating the release notes based on Milestone:
+
+```
+gitreleasemanager.exe create -m 0.1.0 -u bob -p password -o repoOwner -r repo
+
+gitreleasemanager.exe create -milestone 0.1.0 -username bob -password password -owner repoOwner -repository repo
+```
+
+Use GitReleaseManager to create a Release, taking the release notes as an input parameter:
+
+```
+gitreleasemanager.exe create -i c:\temp\releasenotes.md -n 0.1.0 -u bob -p password -o repoOwner -r repo
+
+gitreleasemanager.exe create -inputFilePath c:\temp\releasenotes.md -name 0.1.0 -username bob -password password -owner repoOwner -repository repo
+```

docs/commands/export.md

@@ -1 +1,27 @@
-export
+# Export
+
+This command will export all the release notes for a given repository on GitHub.  The generated file will be in Markdown format, and the contents of the exported file is configurable using the GitReleaseManager.yaml file, per repository.
+
+There are two modes of operation when exporting Release Notes. GitReleaseManager can either export all Release Notes, or can export only a specific Release, using the tagName parameter.
+
+## **Required Parameters**
+  * `-u, -username`: The username to access GitHub with.
+  * `-p, -password`: The password to access GitHub with.
+  * `-o, -owner`: The owner of the repository.
+  * `-r, -repository`: The name of the repository.
+  * `-f, -fileOutputPath`: Path to the file export releases.
+
+## **Optional Parameters**
+  * `-t, -tagName`: The name of the release (Typically this is the generated SemVer Version Number).
+  * `-d, -targetDirectory`: The directory on which GitReleaseManager should be executed. Defaults to current directory.
+  * `-l, -logFilePath`: Path to where log file should be created. Defaults to logging to console.
+
+## **Examples**
+
+Use GitReleaseManager to export all Release Notes:
+
+```
+gitreleasemanager.exe export -u bob -p password -o repoOwner -r repo -f c:\temp\releases.md
+
+gitreleasemanager.exe export -username bob -password password -owner repoOwner -repository repo -fileOutputPath c:\temp\releases.md
+```

docs/commands/init.md

@@ -1 +1,23 @@
-init
+# Init
+
+The Init command is used to create GitReleaseManager.yaml which controls the configurable options of GitReleaseManager
+
+## **Optional Parameters**
+  * `-d, -targetDirectory`: The directory on which GitReleaseManager should be executed. Defaults to current directory.
+  * `-l, -logFilePath`: Path to where log file should be created. Defaults to logging to console.
+
+## **Examples** 
+
+Create a new GitReleaseManager.yaml file in the current working directory:
+
+```
+gitreleasemanager.exe init
+```
+
+Create a new GitReleaseManager.yaml file in a specific directory:
+
+```
+gitreleasemanager.exe init -d c:\temp
+
+gitreleasemanager.exe init -targetDirectory c:\temp
+```

docs/commands/publish.md

@@ -1 +1,22 @@
-publish
+# Publish
+
+While it would be possible to automatically publish a set of release notes in a single command, it is envisioned that some manual intervention is required to ensure that all release notes are valid, and any additional information is added to the release, prior to publishing.  As a result, a second command is required to actually publish a release.
+
+## **Required Parameters**
+  * `-u, -username`: The username to access GitHub with.
+  * `-p, -password`: The password to access GitHub with.
+  * `-o, -owner`: The owner of the repository.
+  * `-r, -repository`: The name of the repository.
+  * `-t, -tagName`: The name of the release (Typically this is the generated SemVer Version Number).
+
+## **Optional Parameters**
+  * `-d, -targetDirectory`: The directory on which GitReleaseManager should be executed. Defaults to current directory.
+  * `-l, -logFilePath`: Path to where log file should be created. Defaults to logging to console.
+
+## **Examples** 
+
+```
+gitreleasemanager.exe publish -t 0.1.0 -u bob -p password -o repoOwner -r repo
+
+gitreleasemanager.exe publish -tagName 0.1.0 -username bob -password password -owner repoOwner -repository repo
+```

docs/commands/show-config.md

@@ -1 +1,23 @@
-show config
+# Show Config
+
+The showconfig command is used to display the current configuration for GitReleaseManager when executed against a specific directory.
+
+## **Optional Parameters**
+  * `-d, -targetDirectory`: The directory on which GitReleaseManager should be executed. Defaults to current directory.
+  * `-l, -logFilePath`: Path to where log file should be created. Defaults to logging to console.
+
+## **Examples**
+
+Show the configuration for the current working directory:
+
+```
+gitreleasemanager.exe showconfig
+```
+
+Show the configuration for a specific directory:
+
+```
+gitreleasemanager.exe showconfig -d c:\temp
+
+gitreleasemanager.exe showconfig -targetDirectory c:\temp
+```

docs/configuration/create-configuration.md

@@ -1 +1,29 @@
-create
+# Example of Create Configuration
+
+When creating a release, it is possible to control the look and feel of the release notes, using settings within the GitReleaseManager.yaml file.
+
+Out of the box, GitReleaseManager creates a simple list of Issues included within a milestone, split into the labels that have been configured.  However, it is possible to include additional information in the form of a footer, which provides additional information, for example, where an installation of the release can be located.
+
+Take for example the GitReleaseManager.yaml file which is used by the [ChocolateyGUI](https://github.com/chocolatey/ChocolateyGUI) project:
+
+```
+create:
+  include-footer: true
+  footer-heading: Where to get it
+  footer-content: You can download this release from [chocolatey.org](https://chocolatey.org/packages/chocolateyGUI/{milestone})
+  footer-includes-milestone: true
+  milestone-replace-text: '{milestone}'
+```
+
+This would result in the following [release notes](https://github.com/chocolatey/ChocolateyGUI/releases/tag/0.13.1) being generated:
+
+![Example Release Notes]()
+
+<div class="admonition note">
+    <p class="first admonition-title">Note</p>
+    <p class="last">
+        The generated URL for the link to Chocolatey.org includes the milestone number.  The complete URL is https://chocolatey.org/packages/chocolateyGUI/0.13.1.  This was achieved by using a regular expression replacement of the [footer-content](doc:default-configuration), using the [milestone-replace-text](doc:default-configuration) property as the text to replace with the actual milestone.
+
+This approach can be used for any project, this example simply shows what is done in the ChocolateyGUI project.
+    </p>
+</div>