-
Task
-
Resolution: Won't Fix
-
Minor
-
None
-
-
atlantic
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 michaelneale please assign to final implementer otherwise just close it.
- relates to
-
JENKINS-35842 Allow ExtensionPoint's to be enumerated
-
- Resolved
-
[JENKINS-38482] Documentation of ExtensionPoints and their attributes they get passed (data types)
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
@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?
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.
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.
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).
tscherler 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.