Merge pull request #40 from Praqma/ready/39-Add-statement-of-work-for-pipeline-job-compliance-and-branch-context-feature

SoW pipeline jobs (#37), branch context (#38)

Author: Bue Petersen

docs/SoW/branch-context.md

@@ -0,0 +1,30 @@
+# Branch Context for PIP - statement of Work
+
+## Problem
+
+When an integration is not successful the only place to find information is in the relevant Jenkins build. If the failures are not noticed and handled immediately you can easily loose the overview of the state of all the ready branches when you only look at the branches in your DVCS. Are the ready branches there because they failed, or are they waiting in queue? To see the status you would have to visit the Jenkins server, but it might have been easier to detect the problem in context of some branch naming conventions.
+
+## Solution
+We propose a solution where we supply information about the integration process as a branch context by renaming the ready branches processed.
+The context is applied as follows to a ready-branch pushed to `ready/my-feature`
+* When processing it is renamed `wip/my-feature`
+* When successfully integrated the branch is deleted
+* If integration fails due og merge failure it is left renamed as `merge-failed/my-feature`
+* If build fails (build steps, or any other reason) the branch is left renamed as `build-failed/my-feature`
+
+When the problem is solved, we support that the developer just pushes to the same ready-branch (`ready/my-feature`).
+The plugin cleans up automatically all branches used in the workflow, meaning if success all ``*/my-feature` is deleted.
+
+**Renamed means the original ready/my-feature branch is deleted.**
+
+**Branch context support layers of branch prefixes, so it will also work with ready-branches called `rel-1.0.0/ready/my-feature`.**
+For example a merge failure end in `rel-1.0.0/merged-failed/my-feature`, and when again successful all branches matchin `rel-1.0.0/*/my-feature` is cleaned.
+
+## Implementation
+This new branch context feature will be backwards compatible, and will be available as a configuration choice. We will not include support to configure the renaming patterns, but we can decide the naming patterns together before implementation.
+
+## Deliveries
+New public release with branch context support and updated documentation for this feature.
+
+## Work load
+The workload for this piece of work is estimated to about 40 hours.

docs/SoW/pipeline-job-compliance.md

@@ -0,0 +1,22 @@
+# Pipeline job compliance - statement of work
+
+## Problem
+The easiest way to implement the automation in Jenkins for the [Git Phlow](https://github.com/Praqma/git-phlow ) is to use the Pretested Integration Plugin (PIP), but it can not be used in [Pipeline jobs](https://jenkins.io/doc/book/pipeline/) described with neither [Declarative Pipeline or Scripted Pipeline syntax](https://jenkins.io/doc/book/pipeline/syntax/). It only works in the other popular alternative for scripted jobs, namely Jenkins Job DSL.
+In addition the plugin restricts it use to only the Freestyle job type in Jenkins, not allowing for more creative job setups and the Matrix job types because the pretesting part (get changes, merge and run build step) is not possible to separate from the integration step where we push changes after a successful build
+
+## Solution
+We will implement support for using PIP in Pipeline jobs, both supporting Declarative Pipeline and Scripted Pipeline syntax.
+The plugin will still support Jenkins Job DSL as well.
+We will support separation of the pretesting part from the integration part, so more creative job construction can be used allowing the user to control these steps on their own.
+Officially we will still only support Freestyle jobs.
+
+## Implementation
+To support the solution the plugin will be changed to a Git Plugin extension instead. The integration part where we push the changes will be available as an independent post-build step in Jenkins.
+The plugin will _not_ be backwards compatible.
+
+## Deliveries
+New public release with support for both Pipeline job syntax and Jenkins job DSL syntax. Updated documentation, and examples of all three scripted job types.
+An example of how to use it with Matrix job type, or explanation of outstanding issues for this to work and possible work-arounds.
+
+## Work load
+The work is estimated to about 60 hours of work.