Create docs for v1.0.x

.woodpecker/docs.yml

@@ -48,6 +48,7 @@ steps:
       forge_url: "https://github.com"
       forge_repo_token:
         from_secret: GITHUB_TOKEN_SURGE
+    failure: ignore
     when:
       event: pull_request
       path: *when_path

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## [1.0.0-rc1](https://github.com/woodpecker-ci/woodpecker/releases/tag/1.0.0-rc1) - 2023-07-21
+## [1.0.0-rc1](https://github.com/woodpecker-ci/woodpecker/releases/tag/1.0.0-rc1) - 2023-07-23
 
 * BREAKING
   * Use IDs to access organizations (#1873)

docs/docs/10-intro.md

@@ -1,6 +1,7 @@
 # Welcome to Woodpecker
 
-Woodpecker is a simple CI engine with great extensibility. It runs your pipelines inside [containers](https://opencontainers.org/), so if you are already using them in your daily workflow, you'll love Woodpecker for sure.
+Woodpecker is a simple CI engine with great extensibility. It focuses on executing pipelines inside [containers](https://opencontainers.org/).
+If you are already using containers in your daily workflow, you'll for sure love Woodpecker.
 
 ![woodpecker](woodpecker.png)
 
@@ -26,9 +27,9 @@ steps:
 ### Steps are containers
 
 - Define any container image as context
-  - either use your own and install the needed tools in custom image or
-  - search for available images that are already tailored for your needs on container registries like [Docker Hub](https://hub.docker.com/search?type=image)
-- List the commands that should be executed in your container, in order to build or test your application
+  - either use your own and install the needed tools in a custom image
+  - or search for available images that are already tailored for your needs in image registries like [Docker Hub](https://hub.docker.com/search?type=image)
+- List the commands that should be executed in the container
 
 ```diff
 steps:
@@ -42,7 +43,7 @@ steps:
 ### File changes are incremental
 
 - Woodpecker clones the source code in the beginning
-- Changes to files are persisted through steps as the same volume is mounted to all steps
+- File changes are persisted throughout individual steps as the same volume is being mounted in all steps
 
 ```yaml
 # .woodpecker.yml

docs/docs/20-usage/10-intro.md

@@ -2,9 +2,9 @@
 
 ## Repository Activation
 
-To activate your project navigate to your account settings. You will see a list of repositories which can be activated with a simple toggle. When you activate your repository, Woodpecker automatically adds webhooks to your forge (e.g. GitHub).
+To activate your project navigate to your account settings. You will see a list of repositories which can be activated with a simple toggle. When you activate your repository, Woodpecker automatically adds webhooks to your forge (e.g. GitHub, Gitea, ...).
 
-Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your forge will automatically send a webhook to Woodpecker which will in turn trigger pipeline execution.
+Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your forge will automatically send a webhook to Woodpecker which will in turn trigger the pipeline execution.
 
 ![repository list](repo-list.png)
 
@@ -22,7 +22,7 @@ Webhooks are used to trigger pipeline executions. When you push code to your rep
 
 ## Configuration
 
-To configure your pipeline you should place a `.woodpecker.yml` file in the root of your repository. The .woodpecker.yml file is used to define your pipeline steps. It is a superset of the widely used docker-compose file format.
+To configure your pipeline you must create a `.woodpecker.yml` file in the root of your repository. The `.woodpecker.yml` file is used to define your pipeline steps.
 
 :::note
 We support most of YAML 1.2, but preserve some behavior from 1.1 for backward compatibility.

docs/docs/91-migrations.md

@@ -2,7 +2,11 @@
 
 Some versions need some changes to the server configuration or the pipeline configuration files.
 
-## 1.0.0 (next)
+## next
+
+No breaking changes
+
+## 1.0.0
 
 - The signature used to verify extensions calls (like those used for the [config-extension](./30-administration/100-external-configuration-api.md)) done by the Woodpecker server switched from using a shared-secret HMac to an ed25519 key-pair. Read more about it at the [config-extensions](./30-administration/100-external-configuration-api.md) documentation.
 - Refactored support of old agent filter labels and expression. Learn how to use the new [filter](./20-usage/20-pipeline-syntax.md#labels)

docs/docusaurus.config.js

@@ -214,11 +214,15 @@ module.exports = {
           includeCurrentVersion: true,
           lastVersion: '0.15',
           versions: {
-            current: {
+            'current': {
               label: 'Next',
               banner: 'unreleased',
             },
-            0.15: {
+            '1.0': {
+              label: '1.0.x',
+              banner: 'unreleased',
+            },
+            '0.15': {
               label: '0.15.x',
               banner: 'none',
             },

docs/versioned_docs/version-1.0/10-intro.md

@@ -0,0 +1,94 @@
+# Welcome to Woodpecker
+
+Woodpecker is a simple CI engine with great extensibility. It focuses on executing pipelines inside [containers](https://opencontainers.org/).
+If you are already using containers in your daily workflow, you'll for sure love Woodpecker.
+
+![woodpecker](woodpecker.png)
+
+## .woodpecker.yml
+
+- Place your pipeline in a file named `.woodpecker.yml` in your repository
+- Pipeline steps can be named as you like
+- Run any command in the commands section
+
+```yaml
+# .woodpecker.yml
+steps:
+  build:
+    image: debian
+    commands:
+      - echo "This is the build step"
+  a-test-step:
+    image: debian
+    commands:
+      - echo "Testing.."
+```
+
+### Steps are containers
+
+- Define any container image as context
+  - either use your own and install the needed tools in a custom image
+  - or search for available images that are already tailored for your needs in image registries like [Docker Hub](https://hub.docker.com/search?type=image)
+- List the commands that should be executed in the container
+
+```diff
+steps:
+  build:
+-   image: debian
++   image: mycompany/image-with-awscli
+    commands:
+      - aws help
+```
+
+### File changes are incremental
+
+- Woodpecker clones the source code in the beginning
+- File changes are persisted throughout individual steps as the same volume is being mounted in all steps
+
+```yaml
+# .woodpecker.yml
+steps:
+  build:
+    image: debian
+    commands:
+      - touch myfile
+  a-test-step:
+    image: debian
+    commands:
+      - cat myfile
+```
+
+## Plugins are straightforward
+
+- If you copy the same shell script from project to project
+- Pack it into a plugin instead
+- And make the yaml declarative
+- Plugins are Docker images with your script as an entrypoint
+
+```Dockerfile
+# Dockerfile
+FROM laszlocloud/kubectl
+COPY deploy /usr/local/deploy
+ENTRYPOINT ["/usr/local/deploy"]
+```
+
+```bash
+# deploy
+kubectl apply -f $PLUGIN_TEMPLATE
+```
+
+```yaml
+# .woodpecker.yml
+steps:
+  deploy-to-k8s:
+    image: laszlocloud/my-k8s-plugin
+    settings:
+      template: config/k8s/service.yml
+```
+
+See [plugin docs](./20-usage/51-plugins/10-plugins.md).
+
+## Continue reading
+
+- [Create a Woodpecker pipeline for your repository](./20-usage/10-intro.md)
+- [Setup your own Woodpecker instance](./30-administration/00-setup.md)

docs/versioned_docs/version-1.0/20-usage/10-intro.md

@@ -0,0 +1,75 @@
+# Getting started
+
+## Repository Activation
+
+To activate your project navigate to your account settings. You will see a list of repositories which can be activated with a simple toggle. When you activate your repository, Woodpecker automatically adds webhooks to your forge (e.g. GitHub, Gitea, ...).
+
+Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your forge will automatically send a webhook to Woodpecker which will in turn trigger the pipeline execution.
+
+![repository list](repo-list.png)
+
+> Required Permissions
+>
+>The user who enables a repo in Woodpecker must have `Admin` rights on that repo, so that Woodpecker can add the webhook.
+>
+> Note that manually creating webhooks yourself is not possible. This is because webhooks are signed using a per-repository secret key which is not exposed to end users.
+
+# Webhooks
+
+When you activate your repository Woodpecker automatically add webhooks to your forge (e.g. GitHub). There is no manual configuration required.
+
+Webhooks are used to trigger pipeline executions. When you push code to your repository, open a pull request, or create a tag, your forge will automatically send a webhook to Woodpecker which will in turn trigger pipeline execution.
+
+## Configuration
+
+To configure your pipeline you must create a `.woodpecker.yml` file in the root of your repository. The `.woodpecker.yml` file is used to define your pipeline steps.
+
+:::note
+We support most of YAML 1.2, but preserve some behavior from 1.1 for backward compatibility.
+Read more at: [https://github.com/go-yaml/yaml](https://github.com/go-yaml/yaml/tree/v3)
+:::
+
+Example pipeline configuration:
+
+```yaml
+steps:
+  build:
+    image: golang
+    commands:
+      - go get
+      - go build
+      - go test
+
+services:
+  postgres:
+    image: postgres:9.4.5
+    environment:
+      - POSTGRES_USER=myapp
+```
+
+Example pipeline configuration with multiple, serial steps:
+
+```yaml
+steps:
+  backend:
+    image: golang
+    commands:
+      - go get
+      - go build
+      - go test
+
+  frontend:
+    image: node:6
+    commands:
+      - npm install
+      - npm test
+
+  notify:
+    image: plugins/slack
+    channel: developers
+    username: woodpecker
+```
+
+## Execution
+
+To trigger your first pipeline execution you can push code to your repository, open a pull request, or push a tag. Any of these events triggers a webhook from your forge and execute your pipeline.

docs/versioned_docs/version-1.0/20-usage/15-terminology.md

@@ -0,0 +1,42 @@
+# Terminology
+
+## Glossary
+
+- **Woodpecker CI**: The project name around Woodpecker.
+- **Woodpecker**: An open-source tool that executes [pipelines][Pipeline] on your code.
+- **Server**: The component of Woodpecker that handles webhooks from forges, orchestrates agents, and sends status back. It also serves the API and web UI for administration and configuration.
+- **Agent**: A component of Woodpecker that executes [pipelines][Pipeline] (specifically one or more [workflows][Workflow]) with a specific backend (e.g. [Docker][], Kubernetes, [local][Local]). It connects to the server via GRPC.
+- **CLI**: The Woodpecker command-line interface (CLI) is a terminal tool used to administer the server, to execute pipelines locally for debugging / testing purposes, and to perform tasks like linting pipelines.
+- **Pipeline**: A sequence of [workflows][Workflow] that are executed on the code. [Pipelines][Pipeline] are triggered by events.
+- **Workflow**: A sequence of steps and services that are executed as part of a [pipeline][Pipeline]. Workflows are represented by YAML files. Each [workflow][Workflow] has its own isolated [workspace][Workspace], and often additional resources like a shared network (docker).
+- **Steps**: Individual commands, actions or tasks within a [workflow][Workflow].
+- **Code**: Refers to the files tracked by the version control system used by the [forge][Forge].
+- **Repos**: Short for repositories, these are storage locations where code is stored.
+- **Forge**: The hosting platform or service where the repositories are hosted.
+- **Workspace**: A folder shared between all steps of a [workflow][Workflow] containing the repository and all the generated data from previous steps.
+- **Event**: Triggers the execution of a [pipeline][Pipeline], such as a [forge][Forge] event like `push`, or `manual` triggered manually from the UI.
+- **Commit**: A defined state of the code, usually associated with a version control system like Git.
+- **Matrix**: A configuration option that allows the execution of [workflows][Workflow] for each value in the [matrix][Matrix].
+- **Service**: A service is a step that is executed from the start of a [workflow][Workflow] until its end. It can be accessed by name via the network from other steps within the same [workflow][Workflow].
+- **Plugins**: [Plugins][Plugin] are extensions that provide pre-defined actions or commands for a step in a [workflow][Workflow]. They can be configured via settings.
+- **Container**: A lightweight and isolated environment where commands are executed.
+- **YAML File**: A file format used to define and configure [workflows][Workflow].
+- **Dependency**: [Workflows][Workflow] can depend on each other, and if possible, they are executed in parallel.
+- **Status**: Status refers to the outcome of a step or [workflow][Workflow] after it has been executed, determined by the internal command exit code. At the end of a [workflow][Workflow], its status is sent to the [forge][Forge].
+
+## Terms
+
+Sometimes there exist multiple terms that can be used for a thing, we try to define it here once and stick to it.
+
+- environment variables `*_LINK` should be `*_URL`, also in code, use `URL()` instead of `Link` ([Vote](https://framadate.org/jVSQHwIGfJYy82IL))
+- **Pipelines** were previously called **builds**
+- **Steps** were previously called **jobs**
+
+[Pipeline]:  ./20-pipeline-syntax.md
+[Workflow]:  ./25-workflows.md
+[Forge]:     ../30-administration/11-forges/10-overview.md
+[Plugin]:    ./51-plugins/10-plugins.md
+[Workspace]: ./20-pipeline-syntax.md#workspace
+[Matrix]:    ./30-matrix-workflows.md
+[Docker]:    ../30-administration/22-backends/10-docker.md
+[Local]:     ../30-administration/22-backends/20-local.md