RFC: Establish some terminology

[anbraten]

We currently mix some terms in the documentation and in the code. The goal of this issue is to define some terminology which is understandable by new users as well as by experts. Please feel free to comment below to suggest terms or to share your opinions. The current draft will be at the end of this description:

---

pipeline

1. pipeline

Triggered by events like webhooks, crons or manual events

formerly known as build

PRs targetting renaming (renaming done with them)

• Rename build to pipeline in code #1224
• Rename to pipeline in DB and JSONs #1296

2. workflow

formerly known as multi-pipeline pipeline

matrix

A pipeline which is executed with multiple options (a matrix) creates multiple workflows (see 2.)

partly known as axes / axis

workspace

Through the time of a workflow a workspace is shared between all steps. This folder normally contains the repository data and all data that was generated by previous steps of the same workflow.

3. step

A single job with a series of commands executed in a sequence.

executed steps are sometimes called procs, jobs or tasks in code

PRs targetting renaming (renaming done with them)

• Renamed procs/jobs to steps in code #1331

components

agent

Runs pipelines and sends results back to server

server

Head of woodpecker deployment which serves the ui, talks to remotes and sends pipeline execution tasks to agents

cli

A cli tool which can interact with a server and can run additional commands like linting, running pipelines without a server (locally), ...

misc

container

formerly known as docker container

container image

formerly known as docker image

forge

formerly known as SCM, VCS or remote

See https://en.wikipedia.org/wiki/Forge_(software)

PRs targetting renaming (renaming done with them)

• Rename remote to forge #1357

Extendable parts

plugin

A step of a pipeline can use a plugin to run an automated series of commands which can be adjusted by plugin settings

Extension / Addon

A remote service (normally http) which can be configured to replace some internal service. #783

[smainz]

Is it too late to contribute?

My concern is that there is no destiction between the execution of something and the definition of something.

One point of view (without knowing anything about the names used in the code) would be to put here some simple sentences, which can be used in the docs to explain, what woodpecker is doing:

• "Woodpecker executes workflows on your code"
• "Code is stored in repos"
• "Repos are hosted on a forge"
• "The execution of a workflow is triggered by some event"
• "Events can be triggerd by a forge, manually in the UI, by cron or using the cli"
• "A workflow is executed on a commit (defined state) of your code"
• "A workflow consists of one or more jobs / stages"
• "Jobs / stages are isolated from eachother and have their own workspace"
• "Jobs/ stages consist of steps/tasks"
• "Tasks / steps share a common workspace"
• "A job can be configured with a matrix, which results in the execution of the job for each value in the matrix"
• "A Job execution can have a status / result / outcome"
• "Each workflow execution (build?) gets an execution number (build numer?)"
• "All jobs in a workflow share the execution number of the workflow"
• "Jobs or steps can be executed in parallel"
• "Steps are defined either by plugins or by a series of commands run in a container"
• "Stages/jobs are defined in a yaml file"
• "Workflows comprise the yaml files of all stages/jobs stored directly inside .woodpecker directory in the code"

project could be an alternative for code.

[6543]

Thanks for the template ... about the core terminology it's already decided, I updated your text acordingly:

• "Woodpecker executes pipelines on your code"
• "Code is stored in repos"
• "Repos are hosted on a forge"
• "The execution of a pipelines is triggered by some event"
• "Events can be triggerd by a forge, manually in the UI, by cron or using the cli"
• "A pipelines is executed on a commit (defined state) of your code"
• "A pipelines consists of one or more workflows"
• "workflows are isolated from eachother and have their own workspace"
• "workflows consist of steps"
• "Steps share a common workspace"
• "A workflow can be configured with a matrix, which results in the execution of the workflows for each value in the matrix"
• "A workflow execution can have a status / result / outcome"
• "Each pipelines execution gets an execution number"
• "All Steps in a workflow share the execution number of the workflow and have there own number too"
• "Steps can be executed in parallel"
• "Steps are defined either by plugins or by a series of commands run in a container"
• "Workflows are defined in a yaml file"
• "Pipeline comprise a yaml or all files of all workflows stored directly inside .woodpecker directory in the code"
• "A pipeline has at least one workflows"
• "Workflows can depend on each other and are executed in parallel if possible"

[smainz]

Why is this different:

• "Steps can be executed in parallel"
• "Workflows can depend on each other and are executed in parallel if possible"

Only because today you have group:on a step and depends_on: on a workflow (trying to use new terminology). Wouldn't it make sense to have the same systemactic for both? Or is this something for #567?

The numbering is not clear to me:

• "Each pipelines execution gets an execution number"

and:

• "All Steps in a workflow share the execution number of the workflow and have there own number too"

Don't all workflow executions share the execution number of the pipeline execution? At least on triggers a pipeline

Will this terminology have an impact on #567 and the environment variables? If it is helpful, I can check the environment variables in the docs and map it to this terminology.

And one more to add to the simple sentences:

• Workflow and step executions can be based on some conditions

[6543]

I think we should now add a glossary to to the docs and then, we can close this issue :)

[6543]

followup -> #1724