Merge pull request #114 from arvindsv/allow-display-order-weight

Add ability to control display order of pipelines on the GoCD dashboard

CHANGELOG.md

@@ -1,4 +1,6 @@
-### 0.9.2 - Unreleased
+### 0.10.0 (2019-Apr-05)
+
+ * Add support for `display_order` at pipeline level \#114
 
 ### 0.9.1 (2019-Apr-05)
 
@@ -10,76 +12,76 @@
  * support nested lists of stages \#95
  * added syntax to configure new scms \#109
 
-# 0.8.6 (21 Jan 2019)
+### 0.8.6 (2019-Jan-21)
 
-* Changed JSON keys returned by `get-capabilities` call
-* Changed JSON structure returned by `parse-content` call
-* Implemented a new `get-icon` call that will return the icon for this plugin
+ * Changed JSON keys returned by `get-capabilities` call
+ * Changed JSON structure returned by `parse-content` call
+ * Implemented a new `get-icon` call that will return the icon for this plugin
 
-# 0.8.5 (15 Jan 2019)
+### 0.8.5 (2019-Jan-15)
 
  * return json from CLI command
 
-# 0.8.4 (09 Jan 2019)
+### 0.8.4 (2019-Jan-09)
 
  * Add export content metadata
  * Fix plugin settings request and implement handler for plugin config change notification
 
-# 0.8.3 (03 Jan 2019)
+### 0.8.3 (2019-Jan-03)
 
  * Added support for `parse-content`.
 
-# 0.8.2 (12 Dec 2018)
+### 0.8.2 (2018-Dec-12)
 
  * accept stdin input in cli tool
 
-# 0.8.1 (30 Nov 2018)
+### 0.8.1 (2018-Nov-30)
 
  * adds CLI for syntax checking
  * adds docker image with the CLI to releases
 
-# 0.8.0 (9 Nov 2018)
+### 0.8.0 (2018-Nov-09)
 
  * added inverse transforms and config-repo 2.0 API support
  * updated to gradle 4.10.2
 
-# 0.7.0 (9 Jul 2018)
+### 0.7.0 (2018-Jul-09)
 
  * introduces `format_version: 3` and external fetch task
 
-# 0.6.2 (13 Mar 2018)
+### 0.6.2 (2018-Mar-13)
 
  * fix ability to set custom file pattern per configuration repository
 
-# 0.6.1 (23 Feb 2018)
+### 0.6.1 (2018-Feb-23)
 
  * switch to EsotericSoftware's yamlbeans
 
-# 0.6.0 (26 Oct 2017)
+### 0.6.0 (2017-Oct-26)
 
  * adds support for referencing templates and specifying parameters
  * adds better support for YAML aliases
  * introduces format_version field, with future work for v2 format
 
-# 0.5.0 (15 Sep 2017)
+### 0.5.0 (2017-Sep-15)
 
  * new release build tasks
  * added configrepo material type
  * added p4 material type support
 
-# 0.4.0 (16 Dec 2016)
+### 0.4.0 (2016-Dec-16)
 
  * fixed IO error reporting
  * added elastic_profile_id in job
 
-# 0.3.0 (07 Nov 2016)
+### 0.3.0 (2016-Nov-07)
 
  * added validation of duplicate keys
 
-# 0.2.0 (21 Oct 2016)
+### 0.2.0 (2016-Oct-21)
 
 * added optional `timeout` field to job
 
-# 0.1.0 (16 Jul 2016)
+### 0.1.0 (2016-Jul-16)
 
 Initial release.

README.md

@@ -25,33 +25,27 @@ so you can explain why pipeline/environment it is configured like this.
 
 ## Setup
 
+**Step 1**: GoCD versions newer than `17.8.0` already have the plugin bundled. You don't need to install anything.
+
 If you're using GoCD version *older than 17.8.0*, you need to install the plugin in the GoCD server. Download it from
 [the releases page](https://github.com/tomzo/gocd-yaml-config-plugin/releases) and place it on the GoCD server in
 `plugins/external` [directory](https://docs.gocd.org/current/extension_points/plugin_user_guide.html).
 
-Add `config-repos` element right above first `<pipelines /> and <artifactStores /> if present`. Then you can
-add any number of YAML configuration repositories as such:
 
-```xml
-<config-repos>
-  <config-repo pluginId="yaml.config.plugin" id="repo1">
-    <git url="https://github.com/tomzo/gocd-yaml-config-example.git" />
-  </config-repo>
-</config-repos>
-...
-<artifactStores />
-<pipelines />
-```
 
-In your config repo (tomzo/gocd-yaml-config-example.git in this case), ensure that your gocd yaml config is suffixed with ".gocd.yaml". Any file ending in ".gocd.yaml" is picked up by the plugin. Give it a minute or so for the polling to happen. Once that happens, you should see your pipeline(s) on your dashboard.
+**Step 2**: Follow [the GoCD documentation](https://docs.gocd.org/current/advanced_usage/pipelines_as_code.html#storing-pipeline-configuration-in-json) to add a new configuration repository.
+
+You can use the example repository at: `https://github.com/tomzo/gocd-yaml-config-example.git`.
+
+In your config repo (`tomzo/gocd-yaml-config-example.git` in this case), ensure that your GoCD yaml config is suffixed with `.gocd.yaml`. Any file ending in `.gocd.yaml` is picked up by the plugin. Give it a minute or so for the polling to happen. Once that happens, you should see your pipeline(s) on your dashboard.
 
 ### Example
 
 More examples are in [test resources](src/test/resources/examples/).
 
 ```yaml
 #ci.gocd.yaml
-format_version: 3
+format_version: 4
 environments:
   testing:
     environment_variables:
@@ -64,6 +58,7 @@ environments:
 pipelines:
   mypipe1: # definition of mypipe1 pipeline
     group: mygroup # note that the group name can contain only of alphanumeric & underscore characters
+    display_order: 10
     label_template: "${mygit[:8]}"
     lock_behavior: none
     parameters: # list of parameters that can be configured for a pipeline
@@ -115,7 +110,7 @@ pipelines:
 
 By default GoCD configuration files should end with `.gocd.yaml` or `.gocd.yml`.
 
-You can set custom file pattern per configuration repository like this:
+You can set a custom file pattern per configuration repository using the GoCD configuration UI or in the config XML like this:
 
 ```xml
 <config-repos>
@@ -133,7 +128,7 @@ You can set custom file pattern per configuration repository like this:
 
 ## Issues and questions
 
- * If you have **questions on usage**, please ask them on the [gitter chat root dedicated for configrepo-plugins](https://gitter.im/gocd/configrepo-plugins?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+ * If you have **questions on usage**, please ask them on the [gitter chat room dedicated for configrepo-plugins](https://gitter.im/gocd/configrepo-plugins?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
  * If you think there is a bug, or you have an idea for a feature and *you are not sure if it's plugin's or [GoCD](https://github.com/gocd/gocd/issues) fault/responsibity*, please ask on the chat first too.
 
 Please note this brief overview of what is done by the plugin:
@@ -227,6 +222,7 @@ Feel free to improve it!
 1. [Parameters](#parameters)
 1. [Pipeline](#pipeline)
     * [Tabs](#tabs)
+    * [Controlling the display order](#display-order-of-pipelines)
     * [Tracking tool](#tracking-tool)
     * [Timer](#timer)
     * [Locking](#pipeline-locking)
@@ -259,40 +255,55 @@ Feel free to improve it!
 
 # Format version
 
-Please note that it is now recommended to declare `format_version` in each `gocd.yaml` file.
-Version `3` was introduced in GoCD v18.7.0
-Currently it is recommended to declare consistent version in all your files:
+Please note that it is now recommended to declare `format_version` in each `gocd.yaml` file, consistent across all your files.
+
+#### GoCD server version from 19.3.0 and beyond
+
+Supports `format_version` value of `4`. In this version, support has been added to control the [display order of pipelines](#display-order-of-pipelines).
 
-For **GoCD < 17.12**:
+This server version also supports `format_version` of `3` and `2`. Using a newer `format_version` includes all the behavior of the previous versions too.
 
 ```yaml
-format_version: 1
+format_version: 4
 pipelines:
   ...
 environments:
 ```
 
-For **GoCD >= 17.12 && GoCD < 18.7.0**:
+#### GoCD server version from 18.7.0 to 19.2.0
+
+Supports `format_version` value of `3`. In this version [fetch artifact](#fetch) format was changed to include `artifact_origin`.
+
+This server version also supports `format_version` of `2`. Using a newer `format_version` includes all the behavior of the previous versions too.
 
 ```yaml
-format_version: 2
+format_version: 3
 pipelines:
   ...
 environments:
 ```
 
-For **GoCD >= 18.7.0**:
+#### GoCD server version from 17.12.0 to 18.6.0
+
+Supports `format_version` value of `2`. In this version [pipeline locking](#pipeline-locking) behavior was changed.
 
 ```yaml
-format_version: 3
+format_version: 2
 pipelines:
   ...
 environments:
 ```
 
-Format version 2 only changes the way [pipeline locking is configured](#pipeline-locking)
+#### GoCD server version up to 17.11.0
+
+Supports `format_version` value of `1`. This is the initial version.
 
-Format version 3 introduces support for external artifact configs.
+```yaml
+format_version: 1
+pipelines:
+  ...
+environments:
+```
 
 # Pipeline
 
@@ -366,6 +377,29 @@ mypipe:
 Please note:
  * Pipeline declares a group to which it belongs
 
+<a name="display-order-of-pipelines"/>
+
+### Controlling the display order
+
+When `format_version` is `4` (see [above](#format-version)), the order of display of pipelines on the GoCD dashboard can be influenced by setting the `display_order` property.
+
+- This is an integer property and the pipelines in a pipeline group will be ordered by this value.
+- The default value for this property is `-1`.
+- Pipelines defined in GoCD's config XML will also default to -1.
+- If multiple pipelines have the same `display_order` value, their order relative to each other will be indeterminate.
+
+```json
+mypipeline1:
+  group: group1
+  display_order: 10
+
+mypipeline2:
+  group: group1
+  display_order: -10
+```
+
+In the above example, since both pipelines are in the same group, `pipeline2` will be shown ahead of `pipeline1`. If any pipelines are defined in the GoCD config XML, then they will appear in between these two pipelines.
+
 ### Tracking tool
 
 ```yaml
@@ -386,7 +420,7 @@ See [XML reference](https://docs.gocd.org/current/configuration/configuration_re
 
 ### Pipeline locking
 
-For **GoCD >= 17.12 and `format_version: 2`**:
+For **GoCD >= 17.12 and `format_version: 2` and above**:
 
 ```yaml
 lock_behavior: none
@@ -1022,7 +1056,7 @@ Aliases can be defined anywhere in the configuration as long as they are valid c
 There is also a dedicated top-level `common` section which allows you to have all aliases in one place and where you don't need to worry about correct placement within the configuration.
 
 ```yaml
-format_version: 3
+format_version: 4
 common:
   verbose_arg: &verbose_arg "VERBOSE=true"
   build_tasks: &build_tasks
@@ -1052,7 +1086,7 @@ pipelines:
 
 Similarly stages can be re-used:
 ```yaml
-format_version: 3
+format_version: 4
 common:
   build_stages: &build_stages
     - stage1:

build.gradle

@@ -7,7 +7,7 @@ plugins {
 }
 
 group 'cd.go.plugin.config.yaml'
-version "0.9.2"
+version "0.10.0"
 
 apply plugin: 'java'
 apply plugin: "com.github.jk1.dependency-license-report"

src/main/java/cd/go/plugin/config/yaml/transforms/PipelineTransform.java

@@ -9,6 +9,7 @@
 import java.util.List;
 import java.util.Map;
 
+import static cd.go.plugin.config.yaml.JSONUtils.addOptionalInt;
 import static cd.go.plugin.config.yaml.JSONUtils.addOptionalValue;
 import static cd.go.plugin.config.yaml.YamlUtils.*;
 import static cd.go.plugin.config.yaml.transforms.EnvironmentVariablesTransform.JSON_ENV_VAR_FIELD;
@@ -26,6 +27,7 @@ public class PipelineTransform {
     private static final String JSON_PIPELINE_TIMER_FIELD = "timer";
     private static final String JSON_PIPELINE_MATERIALS_FIELD = "materials";
     private static final String JSON_PIPELINE_STAGES_FIELD = "stages";
+    private static final String JSON_PIPELINE_DISPLAY_ORDER_FIELD = "display_order_weight";
 
     private static final String YAML_PIPELINE_GROUP_FIELD = "group";
     private static final String YAML_PIPELINE_TEMPLATE_FIELD = "template";
@@ -37,6 +39,7 @@ public class PipelineTransform {
     private static final String YAML_PIPELINE_TIMER_FIELD = "timer";
     private static final String YAML_PIPELINE_MATERIALS_FIELD = "materials";
     private static final String YAML_PIPELINE_STAGES_FIELD = "stages";
+    private static final String YAML_PIPELINE_DISPLAY_ORDER_FIELD = "display_order";
 
     private final MaterialTransform materialTransform;
     private final StageTransform stageTransform;
@@ -65,6 +68,7 @@ public JsonObject transform(Map.Entry<String, Object> entry) {
         Map<String, Object> pipeMap = (Map<String, Object>) entry.getValue();
 
         addOptionalString(pipeline, pipeMap, JSON_PIPELINE_GROUP_FIELD, YAML_PIPELINE_GROUP_FIELD);
+        addOptionalInteger(pipeline, pipeMap, JSON_PIPELINE_DISPLAY_ORDER_FIELD, YAML_PIPELINE_DISPLAY_ORDER_FIELD);
         addOptionalString(pipeline, pipeMap, JSON_PIPELINE_TEMPLATE_FIELD, YAML_PIPELINE_TEMPLATE_FIELD);
         addOptionalString(pipeline, pipeMap, JSON_PIPELINE_LABEL_TEMPLATE_FIELD, YAML_PIPELINE_LABEL_TEMPLATE_FIELD);
         addOptionalBoolean(pipeline, pipeMap, JSON_PIPELINE_PIPE_LOCKING_FIELD, YAML_PIPELINE_PIPE_LOCKING_FIELD);
@@ -106,6 +110,7 @@ public Map<String, Object> inverseTransform(Map<String, Object> pipeline) {
         addOptionalValue(pipelineMap, pipeline, JSON_PIPELINE_PIPE_LOCKING_FIELD, YAML_PIPELINE_PIPE_LOCKING_FIELD);
         addOptionalValue(pipelineMap, pipeline, JSON_PIPELINE_LOCK_BEHAVIOR_FIELD, YAML_PIPELINE_LOCK_BEHAVIOR_FIELD);
         addOptionalValue(pipelineMap, pipeline, JSON_PIPELINE_TRACKING_TOOL_FIELD, YAML_PIPELINE_TRACKING_TOOL_FIELD);
+        addOptionalInt(pipelineMap, pipeline, JSON_PIPELINE_DISPLAY_ORDER_FIELD, YAML_PIPELINE_DISPLAY_ORDER_FIELD);
 
         addInverseTimer(pipelineMap, pipeline);