1070756 - provisioner: Worker type specific documentation

Status: RESOLVED WONTFIX

(Taskcluster :: Services, defect)

Description

[James Lal [:lightsofapollo]]

One of the benefits of having named worker-types is we can incrementally deploy new features but only opt-in as needed... Giving us lots of time to develop "production" workers without breaking existing workflows. Ideally we could couple docs directly with worker types so particular versions of the docker-worker (or other workers) can co-exist nicely without pushing a bunch of different docs to the docker-worker pages.

Comment 1

[Jonas Finnemann Jensen (:jonasfj)]

I've been thinking a bit about this issue today... and I'm not sure the solution is to extend the provisioner with some sort of logic that allows us to publish documentation for each workerType.

We're going to have multiple similar cases... Maybe we should define a reference.json format like the ones we have for exchanges and apis. But instead it of apis or exchange the contents is just markdown pages... This way the human readable documentation for each component could live in their respective repositories and be automatically deployed to reference.taskcluster.net when the code is pushed to production.

For docker-worker we might not want to push the reference every time we launch docker-worker, but we could easily do it every time we deploy a worker...

The document format could be extended to support images and HTML tags like <div data-json-schema="http://..."></div> for quickly rendering JSON schemas.

Note: I'm also thinking that we should convert schemas.taskcluster.net and references.taskcluster.net to heroku apps.. Such that it's easy to list references, references can be deleted, and permission to put references can be managed with taskcluster credentials and scopes, instead of creating an AWS user for each component just so they can upload schemas and references.

I think this would be a pretty quick hack... And give us HTTPS for schemas and references, as is we do have components that loads schemas from schemas.taskcluster.net inorder to reuse them for validation.

Comment 2

[Jonas Finnemann Jensen (:jonasfj)]

As mentioned in bug 1056282.

I propose the following:
http://docs.taskcluster.net/tools/task-graph-inspector/#--0bnelnSZevH2Ju-GNWgQ/yA1mxgXvQKuyh84JmstOLw/0

Comment 3

[John Ford [:jhford] CET/CEST Berlin Time]

bug 1203083 will track adding a description field to worker types, but I think that we should keep documentation generation out of the provisioner itself.