Uploaded image for project: 'Jenkins'
  1. Jenkins
  2. JENKINS-43053

Allow user to document their pipeline in model friendly way

      As https://issues.jenkins-ci.org/browse/JENKINS-38864 is likely to be a bit of rocket science, there is still a need to allow users to document their pipelines in a model friendly way, that the blue ocean editor (for example) can read, and allow users to edit. 

       

      The comments may also be useful for people diagnosing broken steps etc

       

      If there was a way to annotate or have a meta data field for parts of the pipeline declarative model, this could be really helpful. 

      In terms of syntax, I don't have concrete ideas - it could be an attribute, an annotation, or someting. Anything really. 

          [JENKINS-43053] Allow user to document their pipeline in model friendly way

          Michael Neale added a comment -

          For your consideration abayer and hrmpw

          Michael Neale added a comment - For your consideration abayer and hrmpw

          James Dumay added a comment - - edited

          Could this also serve the purpose of defining step names etc for the editor? Perhaps we should bring back the idea of label?

          stage ('Build') {
            steps {
              label(name: 'Run maven', description:'Run Maven before packaging') {
                sh 'mvn dependencies:resolve'
                sh 'mvn clean install'
              }
            }
          }
          

          Then the visualization could collapse both shell script steps into a single step called 'Run Maven' and we could even use the description as extra information on hover etc.

          Making it step based would allow documenting within the editor.

          Perhaps we could add this to the stage too:

          stage (name: 'Build', description: 'cool description for this stage') {
             ...
          }
          

          James Dumay added a comment - - edited Could this also serve the purpose of defining step names etc for the editor? Perhaps we should bring back the idea of label ? stage ( 'Build' ) { steps { label(name: 'Run maven' , description: 'Run Maven before packaging' ) { sh 'mvn dependencies:resolve' sh 'mvn clean install' } } } Then the visualization could collapse both shell script steps into a single step called 'Run Maven' and we could even use the description as extra information on hover etc. Making it step based would allow documenting within the editor. Perhaps we could add this to the stage too: stage (name: 'Build' , description: 'cool description for this stage' ) { ... }

          Liam Newman added a comment - - edited

          The problem is that steps aren't allowed in some places you'd want to put documenting comments.

          jamesdumay
          Stages and nested-stages seem like they'd address the `label` scenario.

          Having a way to give individual steps more meaningful display names is also good, and if we can have consistent way do both documenting and step labeling, that'd be great. But they may not line up perfectly.

          The annotation route (if I understand it correctly) might look something like:

          @Comment('This is a comment helps someone editing this pipeline understand the intent.')
          @Description('This a description that is visible to the end user when they look at the details of this stage.')
          stage ('Build') {
            steps {
                @Title('Resolve Maven Dependencies')
                @Description('This a description that is visible to the end user when they look at the details of this step.')
                sh 'mvn dependencies:resolve'
                @Title('Maven Clean and Install')
                sh 'mvn clean install'
              }
            }
          }
          

          Liam Newman added a comment - - edited The problem is that steps aren't allowed in some places you'd want to put documenting comments. jamesdumay Stages and nested-stages seem like they'd address the `label` scenario. Having a way to give individual steps more meaningful display names is also good, and if we can have consistent way do both documenting and step labeling, that'd be great. But they may not line up perfectly. The annotation route (if I understand it correctly) might look something like: @Comment( 'This is a comment helps someone editing this pipeline understand the intent.' ) @Description( 'This a description that is visible to the end user when they look at the details of this stage.' ) stage ( 'Build' ) { steps { @Title( 'Resolve Maven Dependencies' ) @Description( 'This a description that is visible to the end user when they look at the details of this step.' ) sh 'mvn dependencies:resolve' @Title( 'Maven Clean and Install' ) sh 'mvn clean install' } } }

          James Dumay added a comment -

          bitwiseman annotations don't really fit the style we are promoting in declarative. I believe Libraries used annotations and we ended up going a different route for them in declarative.

          James Dumay added a comment - bitwiseman annotations don't really fit the style we are promoting in declarative. I believe Libraries used annotations and we ended up going a different route for them in declarative.

          James Dumay added a comment -

          Alternative - allow a comment {} block anywhere?

          James Dumay added a comment - Alternative - allow a comment { } block anywhere?

          Liam Newman added a comment -

          jamesdumay abayer
          I'm okay with that too. My only strong feeling is that whatever we do should:
          1. not require changes to the way existing Scripted Pipeline steps are used
          2. be consistent and usable throughout Declarative with reasonable liimitation. For example, it might be reasonable to say comments can't be added inside the environment directive due to technical limitations. I'm open to discussing.
          3. (optional) flexible enough to cover the labelling concept you mentioned or a reasonable parallel example of how the labeling might also be done.

          Liam Newman added a comment - jamesdumay abayer I'm okay with that too. My only strong feeling is that whatever we do should: 1. not require changes to the way existing Scripted Pipeline steps are used 2. be consistent and usable throughout Declarative with reasonable liimitation. For example, it might be reasonable to say comments can't be added inside the environment directive due to technical limitations. I'm open to discussing. 3. (optional) flexible enough to cover the labelling concept you mentioned or a reasonable parallel example of how the labeling might also be done.

          James Dumay added a comment -

          bitwiseman I'd like to call out that nesting stages isn't an appropriate solution for this problem. It's a huge, nuanced problem on its own - just read JENKINS-38442 to get a sense of that.

          James Dumay added a comment - bitwiseman I'd like to call out that nesting stages isn't an appropriate solution for this problem. It's a huge, nuanced problem on its own - just read JENKINS-38442 to get a sense of that.

            Unassigned Unassigned
            michaelneale Michael Neale
            Votes:
            2 Vote for this issue
            Watchers:
            6 Start watching this issue

              Created:
              Updated: