Drone

Rolling out new documentation

We are rolling out new documentation at docs.drone.io.

The good news is the documentation is much more detailed and comprehensive. We have even published formal specifications for our yaml syntax!

The bad news is that we expect some initial confusion due to the fact that Drone now supports multiple types of pipelines, where each type of pipeline defines its own unique yaml syntax. For example:

  • the docker runner executes commands in docker containers
  • the exec runner executes commands directly on the host machine (no docker involved)
  • the ssh runner executes commands on a remote server (no docker involved)
  • the digitalocean runner creates a digital ocean instance per-pipeline and executes commands directly on the vm (no docker involved)

Overall I am really excited to support different types of pipelines. There are many workloads and use cases that are poorly suited for containers, such as macOS builds. There are also certain workloads that are better suited for traditional virtual machines instead of containers. Drone will now be able to support these projects.

The challenge is that support for different runners and pipeline types adds a new dimension of complexity to the documentation. I found it very difficult to structure the documentation and very difficult to explain these concepts to readers, and route them to the appropriate pipeline or runner documentation.

The full documentation will be published to GitHub this week (most of the documentation is already published) and we hope people will help us improve the structure and clarity. We understand there will be some growing pains the first few weeks, and we appreciate your help and patience as we gather feedback and make improvements.

Finally, please be constructive with feedback. If you are going to comment on the quality of the documentation, please be sure to provide us with actionable feedback and examples of things that can be improved. Thanks!

5 Likes

Hi

Great, Thanks for the great work - the product is very great, but docs are sometimes confusing (no offence )

Just with a quick look it seems that DRONE_RUNNER_NETWORKS variable is still missing in documentation

while other variable DRONE_RUNNER_MAX_PROCS - is documented - but I cannot find it in GitHub search ?

I guess all the DRONE_RUNNER_xxx need to be revised

Could you be more specific? Is it confusing because we are missing the previously mentioned configuration parameters in the Docker Runner reference section (e.g. DRONE_RUNNER_NETWORKS)? Or is there something else confusing about the documentation we need to address?

We do still need to audit and update the Docker runner environment variables, and you are correct a few could still be missing or out-of-sync with the codebase.
https://docker-runner.docs.drone.io/installation/reference/

We have audited all configuration parameters for the server and other runners, which I can confirm are completely up-to-date.

I guess it sort of general feeling… hard to explain…

Like today I was looking how to solve one issue with image pulling

basically my case was solvable with step > pull: if-not-exists

I knew it was called some thing like that - so I went to Docker-runner , and then to Steps section - https://docker-runner.docs.drone.io/configuration/steps/

and pull option was not there…

I was able to find that option on other section… but my guess that ideally on page steps must describe ALL possible options

I guess that’s my common feeling about every time I look something in docs - have to click many pages to find exact setting…

Maybe what can help is like a single page that have reference too all possible yaml options with examples - like for instance docker-compose - https://docs.docker.com/compose/compose-file/

so yeah… reference for ALL options for yaml and reference for ALL options for ENV vars

thanks for clarifying! You might also want to check out the specification which defines all fields and types: https://docker-runner.docs.drone.io/specification/

I definitely like the new documentation page, albeit it’s not yet perfect, I think finally a source of all the truth about Drone is a godsend to a lot of us, or at least it is for me.

I’ve spent countless hours figuring things out only because the documentation referred to an old version, the documentation was ahead of the Drone release or the link to the documentation was broken, or it simply never existed.

With that being said, I’d definitely suggest versioning the docs with every minor Drone version at least, and do a stricter inspection to make sure the documentation reflects the truth for every release.

I would also make news/changelogs/announcements easily reachable from the documentation site. I’ve only recently accidentally stumbled upon a github issue comment that said that the experimental Kubernetes runners were officially deprecated months ago, but I don’t see any posts or announcements about it.

These are my 2 cents. I appreciate your work, and absolutely love Drone, and I will definitely contribute to the documentation in my spare time whenever it is available.

thanks for taking time to provide feedback

note that starting with Drone 1 we have a compatibility guarantee similar to Go 1 which means we will not break previous releases. So instead of versioning docs, we will do something similar to Go [1] and indicate in which version a specific feature or variable appeared.

[1] https://golang.org/doc/go1.11#godoc

1 Like

:clap::clap::clap: Nice work! Really concise.

Hi @bradrydzewski is there a way to contribute to the documentation? or just by leaving feedback here?

Thanks

2 Likes