Skip to content

Commit

Permalink
Merge branch 'main' into fix-stat-visual
Browse files Browse the repository at this point in the history
  • Loading branch information
qwerty287 committed Dec 23, 2023
2 parents c6bf1c3 + 030db4e commit 84dc2b2
Show file tree
Hide file tree
Showing 9 changed files with 48 additions and 47 deletions.
13 changes: 13 additions & 0 deletions docs/cookbook/2023-12-23-hello-cookbook/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
title: Welcome to Woodpecker's cookbook blog
description: Here, we'll publish various guides and tutorials.
slug: hello-cookbook
authors:
- name: qwerty287
title: Maintainer of Woodpecker
url: https://github.com/qwerty287
image_url: https://github.com/qwerty287.png
hide_table_of_contents: false
---

Welcome to this cookbook blog. Here, we and any other interested user can publish guides and tutorials. If you got something in mind, just add your guide!
3 changes: 1 addition & 2 deletions docs/docs/10-intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,8 +69,7 @@ COPY deploy /usr/local/deploy
ENTRYPOINT ["/usr/local/deploy"]
```

```bash
# deploy
```bash title="deploy"
kubectl apply -f $PLUGIN_TEMPLATE
```

Expand Down
17 changes: 1 addition & 16 deletions docs/docs/92-development/06-guides.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,7 @@ You can find its documentation at [gobook.io/read/gitea.com/xorm](https://gobook

## Add a new migration

Woodpecker uses migrations to change the database schema if a database model has been changed. If for example a developer removes a property `Counter` from the model `Repo` in `server/model/` they would need to add a new migration task like the following example to a file like `server/store/datastore/migration/004_repos_drop_repo_counter.go`:

```go
package migration

import (
"xorm.io/xorm"
)

var alterTableReposDropCounter = task{
name: "alter-table-drop-counter",
fn: func(sess *xorm.Session) error {
return dropTableColumns(sess, "repos", "repo_counter")
},
}
```
Woodpecker uses migrations to change the database schema if a database model has been changed. Add the new migration task into `server/store/datastore/migration/`.

:::info
Adding new properties to models will be handled automatically by the underlying [ORM](#orm) based on the [struct field tags](https://stackoverflow.com/questions/10858787/what-are-the-uses-for-tags-in-go) of the model. If you add a completely new model, you have to add it to the `allBeans` variable at `server/store/datastore/migration/migration.go` to get a new table created.
Expand Down
32 changes: 7 additions & 25 deletions docs/docs/92-development/08-swagger.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,7 @@ You don't require any extra tools on your machine, all Swagger tooling is automa

Here's a typical example of how annotations for Swagger documentation look like...

```text
--- server/api/user.go ---
```go title="server/api/user.go"
// @Summary Get a user
// @Description Returns a user with the specified login name. Requires admin rights.
// @Router /users/{login} [get]
Expand All @@ -30,8 +29,7 @@ Here's a typical example of how annotations for Swagger documentation look like.
// @Param perPage query int false "for response pagination, max items per page" default(50)
```

```text
--- server/model/user.go ---
```go title="server/model/user.go"
type User struct {
ID int64 `json:"id" xorm:"pk autoincr 'user_id'"`
// ...
Expand All @@ -41,41 +39,25 @@ type User struct {
These guidelines aim to have consistent wording in the swagger doc:

- first word after `@Summary` and `@Summary` are always uppercase
- `@Summary` has no . (dot) at the end of the line
- `@Summary` has no `.` (dot) at the end of the line
- model structs shall use custom short names, to ease life for API consumers, using `@name`
- `@Success` object or array declarations shall be short, this means the actual `model.User` struct must have a `@name` annotation, so that the model can be renderend in Swagger
- when pagination is used, `@Parame page` and `@Parame perPage` must be added manually
- `@Param Authorization` is almost always present, there are just a few un-protected endpoints

There are many examples in the server/api package, which you can use a blueprint.
There are many examples in the `server/api` package, which you can use a blueprint.
More enhanced information you can find here <https://github.com/swaggo/swag/blob/main/README.md#declarative-comments-format>

### Manual code generation

#### generate the server's Go code containing the Swagger

```bash
```bash title="generate the server's Go code containing the Swagger"
make generate-swagger
```

##### update the Markdown in the ./docs folder

```bash
```bash title="update the Markdown in the ./docs folder"
make docs
```

##### auto-format swagger related godoc

```bash
```bash title="auto-format swagger related godoc"
go run github.com/swaggo/swag/cmd/swag@latest fmt -g server/api/z.go
```

<!-- markdownlint-disable no-space-in-code -->

**WARNING, known issue**: using swag v1.18.12 , there's a bug when running the `fmt` command,
which makes the swagger generator failing, because it can't find the models/structs/types anymore.
To fix it, please replace `// @name\tModelName` with `// @name ModelName`,
which means, replace the tab (`\t`) with a space (` `).
See <https://github.com/swaggo/swag/pull/1594> == once this is merged and released, the mentioned issue is obsolete.

<!-- markdownlint-enable no-space-in-code -->
2 changes: 1 addition & 1 deletion docs/docs/92-development/09-security.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Security

We take security seriously.
If you discover a security issue, please bring it to their attention right away!
If you discover a security issue, please bring it to our attention right away!

## Reporting a Vulnerability

Expand Down
16 changes: 16 additions & 0 deletions docs/docusaurus.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ const config: Config = {
label: 'API',
},
{ to: 'blog', label: 'Blog', position: 'left' },
{ to: 'cookbook', label: 'Cookbook', position: 'left' },
{
type: 'docsVersionDropdown',
position: 'right',
Expand Down Expand Up @@ -192,6 +193,21 @@ const config: Config = {
};
},
}),
[
'@docusaurus/plugin-content-blog',
{
id: 'cookbook-blog',
/**
* URL route for the blog section of your site.
* *DO NOT* include a trailing slash.
*/
routeBasePath: 'cookbook',
/**
* Path to data on filesystem relative to site dir.
*/
path: './cookbook',
},
],
],
themes: [
path.resolve(__dirname, 'plugins', 'woodpecker-plugins', 'dist'),
Expand Down
1 change: 1 addition & 0 deletions docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
},
"dependencies": {
"@docusaurus/core": "^3.0.0",
"@docusaurus/plugin-content-blog": "^3.0.1",
"@docusaurus/preset-classic": "^3.0.0",
"@easyops-cn/docusaurus-search-local": "^0.40.0",
"@mdx-js/react": "^3.0.0",
Expand Down
3 changes: 3 additions & 0 deletions docs/pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 5 additions & 3 deletions web/src/assets/locales/de.json
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@
"pr_warning": "Bitte sei vorsichtig mit dieser Option, da eine böswillige Person über einen Pull-Request deine Geheimnisse erhalten könnte."
},
"images": {
"desc": "Komma getrennte Liste aller Images, für die dieses Geheimnis verwendet werden kann. Freilassen, um alle Images zu erlauben",
"desc": "Liste aller Images, für die dieses Geheimnis verwendet werden kann. Freilassen, um alle Images zu erlauben",
"images": "Verfügbar für folgende Images"
},
"name": "Name",
Expand Down Expand Up @@ -142,6 +142,7 @@
"errors": {
"not_found": "Angefragtes Objekt wurde nicht gefunden"
},
"global_level_secret": "globales Geheimnis",
"info": "Info",
"login": "Anmelden",
"logout": "Abmelden",
Expand All @@ -162,7 +163,7 @@
"pr_warning": "Bitte sei vorsichtig mit dieser Option, da eine böswillige Person über einen Pull-Request deine Geheimnisse erhalten könnte."
},
"images": {
"desc": "Komma getrennte Liste aller Images, für die dieses Geheimnis verwendet werden kann. Freilassen, um alle Images zu erlauben",
"desc": "Liste aller Images, für die dieses Geheimnis verwendet werden kann. Freilassen, um alle Images zu erlauben",
"images": "Verfügbar für die folgenden Images"
},
"name": "Name",
Expand All @@ -177,6 +178,7 @@
"settings": "Einstellungen"
}
},
"org_level_secret": "Organisationsgeheimnis",
"password": "Passwort",
"pipeline_feed": "Pipeline-Feed",
"repo": {
Expand Down Expand Up @@ -419,7 +421,7 @@
"pr_warning": "Bitte sei vorsichtig mit dieser Option, da eine böswillige Person über einen Pull-Request deine Geheimnisse erhalten könnte."
},
"images": {
"desc": "Durch Kommata getrennte Liste der Images, für die dieses Geheimnis verfügbar ist; leer lassen, um alle Images zuzulassen",
"desc": "Liste der Images, für die dieses Geheimnis verfügbar ist; leer lassen, um alle Images zuzulassen",
"images": "Verfügbar für folgende Images"
},
"name": "Name",
Expand Down

0 comments on commit 84dc2b2

Please sign in to comment.