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

Documentation of ExtensionPoints and their attributes they get passed (data types)

    Details

    • Similar Issues:
    • Epic Link:
    • Sprint:
      atlantic

      Description

      ExtensionPoints are an important part of the JS side of plugins in blue ocean, they should be documented in terms of what data they can get passed and where they are hosted.

      In scope:

      • Find a scheme to document extension points, including param types
      • Find a mechanism to generate static docs from source of what extension points are available, and what module, and publish
      • Find a mechanism to dynamically enumerate extensionpoints and current implementers in a running jenkins instance on a "special" URI

      IN https://github.com/jenkinsci/blueocean-plugin/pull/521

      I take the point which leads to "contract properties" passed to certain ExtensionPoints. ATM we do it on free guess and all properties are passed through anyway.

      However we do not have API style declarations of extension points and the attributes we pass through. Which makes it hard for adopters to create reliable alternatives for our default implementations.

      I say ATM the graph is the only use case that we know of that had used run.id in a certain point of time. For housekeeping I prefer to get rid of it since it is redundant now because we pass full run.

      As started I see your point, but see as well the urgent need to declare ExtensionPoints as API where we can deprecate certain attributes to later drop them. ...and to document them to start with.

      in case you see the urge Michael Neale please assign to final implementer otherwise just close it.

        Attachments

          Issue Links

            Activity

            Hide
            michaelneale Michael Neale added a comment -

            Thorsten Scherler I can't quite tell what is meant by the title etc here - but looking at the linked github, the implied thing is "what are our contracts for what data types are passed to extension points" right?

            ie we really want types? Or is this a more specific question of passing fields vs objects?

            Any clarity appreciated.

            Show
            michaelneale Michael Neale added a comment - Thorsten Scherler I can't quite tell what is meant by the title etc here - but looking at the linked github, the implied thing is "what are our contracts for what data types are passed to extension points" right? ie we really want types ? Or is this a more specific question of passing fields vs objects? Any clarity appreciated.
            Hide
            tscherler Thorsten Scherler added a comment - - edited

            Right now we are defining the extension points in e.g. dashboard like

            extensions:
              - component: AdminNavLink
                extensionPoint: jenkins.logo.top
            ...
            - component: components/PipelineRunGraph
                extensionPoint: jenkins.pipeline.run.result
            

            Where we do not define what properties we are passing to each extensionPoint, neither in which view we are calling it. The above may have some documentation like

            /**
             * Extension point: jenkins.pipeline.run.result
             * Implementer:  components/PipelineRunGraph // maybe better defaultImplementor
             * Declarer: components/RunDetailsPipeline
             * @param {Object} selectedStage the currently displayed stage 
             * @example selectedStage={this.mergedConfig.nodeReducer}
             * @param {Function} callback callback function that we call after click on a graph node
             * @example callback={afterClick}
             * @param {Object} nodes - the nodes we want to display in the pipeline graph
             * @example nodes={nodes[nodeKey].model}
             * @param {String} pipelineName - the name of the pipeline
             * @example pipelineName={name}
             * @param branchName - in case of multibranch we pass the name of the branch
             * @example branchName={isMultiBranch ? params.branch : undefined}
             * @param {Object} run - the currently displayed run
             * @deprecated @param {String} runId - the id of the run
             * @example runId={run.id}
             */
            

            this would be a good start for someone to create her own implementation.

            Does that makes it a bit clearer, @michaelNeale

            Show
            tscherler Thorsten Scherler added a comment - - edited Right now we are defining the extension points in e.g. dashboard like extensions: - component: AdminNavLink extensionPoint: jenkins.logo.top ... - component: components/PipelineRunGraph extensionPoint: jenkins.pipeline.run.result Where we do not define what properties we are passing to each extensionPoint, neither in which view we are calling it. The above may have some documentation like /** * Extension point: jenkins.pipeline.run.result * Implementer: components/PipelineRunGraph // maybe better defaultImplementor * Declarer: components/RunDetailsPipeline * @param { Object } selectedStage the currently displayed stage * @example selectedStage={ this .mergedConfig.nodeReducer} * @param {Function} callback callback function that we call after click on a graph node * @example callback={afterClick} * @param { Object } nodes - the nodes we want to display in the pipeline graph * @example nodes={nodes[nodeKey].model} * @param { String } pipelineName - the name of the pipeline * @example pipelineName={name} * @param branchName - in case of multibranch we pass the name of the branch * @example branchName={isMultiBranch ? params.branch : undefined} * @param { Object } run - the currently displayed run * @deprecated @param { String } runId - the id of the run * @example runId={run.id} */ this would be a good start for someone to create her own implementation. Does that makes it a bit clearer, @michaelNeale
            Hide
            michaelneale Michael Neale added a comment -

            @thorsten it does yes. - where would that documentation live - where the extension point is defined? could it be generated somehow?

            It seems ideally to belong where the extension point itself is defined in (say) jsx, and then a tool could extract it? or else (as keith has suggested) have the UI show it up sometimes with clickable docs?

            There is this ticket: https://issues.jenkins-ci.org/browse/JENKINS-35842 - which I think this should be combined with. Thoughts?

            Show
            michaelneale Michael Neale added a comment - @thorsten it does yes. - where would that documentation live - where the extension point is defined? could it be generated somehow? It seems ideally to belong where the extension point itself is defined in (say) jsx, and then a tool could extract it? or else (as keith has suggested) have the UI show it up sometimes with clickable docs? There is this ticket: https://issues.jenkins-ci.org/browse/JENKINS-35842 - which I think this should be combined with. Thoughts?
            Hide
            tscherler Thorsten Scherler added a comment -

            I am actually keen to do the same for dashboard what I did for the ATH https://jenkinsci.github.io/blueocean-acceptance-test/

            It is based on jsdoc and would be a good starting point to generate documentation out of comments on the code as above. ...and yes the above would resist in RunDetailsPipeline.

            You can assign the ticket to me and I will implement the infrastructure for it on the dashboard as example and then we could add support for the other plugins in the next wave.

            Show
            tscherler Thorsten Scherler added a comment - I am actually keen to do the same for dashboard what I did for the ATH https://jenkinsci.github.io/blueocean-acceptance-test/ It is based on jsdoc and would be a good starting point to generate documentation out of comments on the code as above. ...and yes the above would resist in RunDetailsPipeline. You can assign the ticket to me and I will implement the infrastructure for it on the dashboard as example and then we could add support for the other plugins in the next wave.
            Hide
            tscherler Thorsten Scherler added a comment -

            regarding JENKINS-35842 IMO it is a bit different, but I had this idea to be able to configure extensionPoint implementations in a kind of personalize mode. will comment on the issue.

            Show
            tscherler Thorsten Scherler added a comment - regarding JENKINS-35842 IMO it is a bit different, but I had this idea to be able to configure extensionPoint implementations in a kind of personalize mode. will comment on the issue.
            Hide
            michaelneale Michael Neale added a comment -

            ok - fair enough. Yes the JENKINS-35842 is more to provide an enumeration for a website (but then the details of the extension points need to point to something like this).

            Show
            michaelneale Michael Neale added a comment - ok - fair enough. Yes the JENKINS-35842 is more to provide an enumeration for a website (but then the details of the extension points need to point to something like this).

              People

              • Assignee:
                tscherler Thorsten Scherler
                Reporter:
                tscherler Thorsten Scherler
              • Votes:
                0 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: