close #254 add documentation page

Author: groenborg

ci/CHANGELOG.md

@@ -1,28 +1,25 @@
 ## Changelog
-
+Windows and Jira support is here! Feast on the godness and the docs
 
 #### Features
 
-- deliver is updated to support target configuration, and Jira #230 @groenborg
-you can now deliver work, with settings from the target configuration.. Hurray
+- `phlow web` is updated to support target configuration, and Jira #247 @groenborg
+typing web will open your browser on your issue page or repository.
 
-- wrapup is now support on windows as well #188 @groenborg
-wrapup will now format messages based on GitHub and Jira branches
+- `phlow issues` you can now list jira issues and github issues #246 @groenborg
+phlow issues fetches the 30 most recent issues and prints them in your terminal. Nice
 
-- workon is now updated to support target configuration, and Jira #224 @groenborg
-you can now work on issues located on GitHub and Jira, with settings from the target configuration
+- `wrapup` wrapup now support bitbucket smart commits as well #257 @groenborg
 
+- `config` git phlow now builds upon the gitconfig of git #209 @groenborg
+The .phlow file have been replaced by .gitconfig and the internal of git.
+You can also bootstrap and show your configuration with `git phlow config`
 
 #### Bug Fixes
-- fix configuration for windows #236 @groenborg
-Turns out the config before did not work on windows, however, it does now.
-
-- auth errors are handled when commands using service API are called #240 @groenborg
-a successful bug-hunt resulted in one less error, where the tool basically would explode with errors if commands were executed without authorization
-
+ - git phlow web no longer opens a malformed url #252 @groenborg
 
 #### improvements
-- We removed the beautiful spinner when running `workon` and `deliver` #241 @groenborg
-it might return in future versions, when it no longer messes with the formatting. Never mess with the formatting!
+- we did some spring cleaning this fall and removed a lot of bad code #258 @groenborg
+such deletion, much improvement!
 
-- Error messages have also been improved, from "something happened" to "your hyper drive core melted a super size hole in you spaceship.. Remember to cool it!"
+- we also did some further improvements in the messages that are suppose to help trouble shoot issues!

docs/README.md

@@ -1,67 +1,94 @@
 # Documentation
+### The workflow
+The Praqma workflow - often called The Phlow - is a combination of the Git extension and CI server for automation. In this the CI server is concourse with the git-phlow resource installed.
 
+![image](/docs/images/phlowmodel.svg)
 
-### phlow auth
+The top diagram Shows the steps the entire workflow entails.
+1. You do `git phlow workon` on an issue which has been groomed and is ready to become a feature in your project.
+2. You do `git phlow wrapup` and `git phlow deliver`, to deliver your changes to the remote repository. The branches will be prefixed with `delivery-branch-prefix` from the .gitconfig file.
+3. In the concourse Pipeline we are using the git-phlow tollgate resource, that automate the integration if it passes our toll-gate. It integrate branches prefixed with ready, meaning the job will trigger on such branches and merge the changes with the head of the integration.
+4. Now the tollgate tests will run in the job and if they pass, the already merged changes will be pushed to the integration branch. The ready branch will be deleted if everything goes well so it leaves things nice and clean. 
+
+
+### phlow workon
 ```
-git phlow auth -t <target>
+git phlow workon <issue>
 ```
-Git phlow auth, authorizes towards a chosen service which can be either `github` or `jira`. Auth is used by git phlow to access and manage issues in your chosen provider.
+First step in the workflow is to start work on an issue. Run the command and it will create a local workspace named after the title of the issue.
 
-Auth is dependent on a configuration file unless you are using GitHub.com for your issues and Repositories, in that case you can complete omit using the `--target` flag
+### phlow wrapup
+```
+git phlow wrapup
+```
+Run wrapup to add your changes and make a commit with the `smart commit`syntax that will close an issue when it lands on the master branch.
 
-#### Self hosted services or Jira
-To authenticate with your own hosted service or Jira you _must_ provide a valid configuration (see **Configuration** section). Your configuration must contain a base url to where your service is hosted and the name of the service. When authenticating set your `--target` to the name of the configuration e.g.
+### phlow deliver
+```
+git phlow deliver
+```
+Deliver will pull the latest changes to your branch and try to push it to a ready branch where the CI server is ready to integrate it into the integration branch. 
 
-```ini
-[myjiraconfig]
-    integration_branch = master
-    remote = origin
-    service = jira
-    issue_url = https://my.jira.instance.com
-    delivery_branch_prefix = ready
+If you have no CI server configured to do automatic integration of ready branches you can run a local deliver in stead, and let your local git do the integration
 ```
-```bash
-git phlow auth --target myjiraconfig
+git phlow deliver --local
 ```
 
+### phlow auth
+```
+git phlow auth
+```
+Git phlow auth, authorizes towards a chosen service which can be either `github` or `jira`. Auth is used by git phlow to access and manage issues in your chosen provider.
+
+#### Self hosted services or Jira
+To authenticate with your own hosted service or Jira you _must_ provide a valid configuration (see **Configuration** section). Your configuration must contain a base url to where your service is hosted and the name of the service. When authenticating set your `--target` to the name of the configuration e.g.
+
 ### Configuration
-git phlow is configured via `.phlow`  files, in your local workspace or in the home folder of your computer. The configuration is standard INI files, just like `.gitconfig`.
+git phlow is configured via `.gitconfig`, in your local workspace, this means that git phlow usese git own internal config and can therefore be placed anywhere git can read it e.g. global .gitconfig in you home folder.
+
+To get started with a a `.gitconfig` in your local repository you must first let git know that the filepath must be included, run this command to do so:
+```sh
+git config --local include.path ../.gitconfig
+```
 
-#### Config Block
-Each configuration is has its own block which can be used by setting the block name to `[default]` or by specifying which configuration you want to use by setting it in the git phlow command.
+##### Config Block
+Each configuration is its own block. You can have as many configuration blocks as you want, just as long as they all have the necessary fields. To use a specific block you run a command with the `-t or --target` option with the name of the block. git phlow by default looks for a block named `[phlow]`. So if you name your preferred blovk `phlow` you do not need to use the `-t` flag.
 
 A block consists of following fields.
 
-- `integration_branch` The name of your default integration branch. normally it's `master`
+- `integration-branch` The name of your default integration branch. normally it's master
 - `remote` The name of your remote. By default git sets this to `origin`
 - `service` The service you use for issues.
-- `issue_url` The url to your service where issues are hosted and managed
-- `delivery_branch_prefix` The prefix you want your pretested integration system to look for
+- `issue-api` The url to your api where issues are hosted and managed
+- `issue-web` The url to your webpage where issues are hosted and managed
+- `delivery-branch-prefix` The prefix you want your pretested integration system to look for
 
-#### Supported services
+##### Supported services
 -  `github`
--  `jira` - `auth` command only
+-  `jira`
 
-
-#### Example Configuration
+##### Example Configuration
 ```ini
-[name]
-    integration_branch = master
-    remote = origin
-    service = github
-    issue_url = https://api.github.com
-    pipeline_url = http://concourse.bosh.praqma.cloud/teams/main/pipelines/git-phlow #optional
-    delivery_branch_prefix = ready
+[phlow]
+    remote                 = myfork
+    service                = github
+    integration-branch     = superintegration
+    issue-api              = https://api.github.com
+    issue-web              = https://github.com
+    delivery-branch-prefix = integrate-me-please
 ```
 
-#### Internal Default
-If no  `.phlow`  files are located, git phlow will use an interal default configuration.  The internal configuration is the last resort, and it is strongly recommended to use `.phlow` to keep your projects configuration, even though it mimics the default.
+**important**: When entering the url of your issue service providers, it is important that only the base url is provided, which means no `www.mygithubinstance.com:8080/` but `www.mygithubinstance.com:8080`
+
+##### Internal Default
+If no  `[phlow]`  blocks are located within the git config, git phlow will use an interal default configuration. The internal configuration is the last resort, and it is strongly recommended to use `.gitconfig` to keep your projects configuration, even though it mimics the default.
 
 ```ini
-[default]
-    integration_branch = master
-    remote = origin
-    service = github
-    issue_url = https://api.github.com
-    delivery_branch_prefix = ready
-``` 
+[phlow]
+    remote                 = origin
+    service                = github
+    integration-branch     = master
+    issue-api              = https://api.github.com
+    issue-web              = https://github.com
+    delivery-branch-prefix = ready
+```