https://github.com/kanata2/esa-freshness-patroller

patrol documentations at esa.io
https://github.com/kanata2/esa-freshness-patroller

documentation esa-io golang

Last synced: 26 days ago
JSON representation

patrol documentations at esa.io

• Host: GitHub
• URL: https://github.com/kanata2/esa-freshness-patroller
• Owner: kanata2
• License: mit
• Created: 2022-05-16T00:07:41.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2023-04-17T14:45:11.000Z (over 1 year ago)
• Last Synced: 2024-06-20T10:15:58.825Z (5 months ago)
• Topics: documentation, esa-io, golang
• Language: Go
• Homepage:
• Size: 87.9 KB
• Stars: 4
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
esa-freshness-patroller :cop:

===

This is a PoC to maintain the documentation's freshness in esa.io.  

This is inspired by Google's efforts as described in "Software Engineering at Google".

## How to use

1. Adding one of the following annotations

2. Run `esa-freshness-patroller`

### Annotations

You can use one of the following annotations for including targets of patroller.

Annotations should basicallythe be added at the beginning of the document.

#### (Recommend) 1. fenced code style

Adding a fenced code which has `esa-freshness-patroller` info string to each post.

This must be written in YAML according to the following schema.

| Key | Required | Type | Description |

| --- | -------- | ---- | ----------- |

| `owners` | Yes | Array of string | documentation owner/reviewer |

| `last_checked_at` | Yes | String(format: `YYYY/MM/DD`) | last reviewed date by owner/reviewers |

| `check_interval_days` | No | Number | day for patrolling interval. this takes precedence over oeverall configuration |

| `skip` | No | Bool | excluding from patrolling targets |

| `custom` | No | Mapping(key/value is String) | custom metadata that can be added freely |

Example:

````markdown

```esa-freshness-patroller

owners: [kanata2, kanata1]

last_checked_at: 2022/12/11

interval: 30

skip: false

custom:

  category: daily

  team: SRE

```

````

#### (Opt-in) 2. Simple text style

Adding `Last checked at YYYY/MM/DD by @username,@username2,...` in your documents.

If you want to set `check_interval_days`, `skip` etc, you should use **fenced code style**.

This is disabled by default and should be enabled as needed.

### General configurations

You can set general configurations through CLI arguments, environment variables or config file.

| Name | Required | Type | Environment variable | CLI argument | key for Config file(YAML) |

| ---- | -------- | ---- | -------------------- | ------------ | ----------------- |

| esa.io's API Key | Yes | String | `ESA_API_KEY` | | esaApiKey (not recommended) |

| esa team | Yes | String | `TEAM` | `--team` | team | 

| esa's search query | Yes | String | `QUERY` | `--query` | query |

| config file | No(default: ./config.yaml) | String | `CONFIG` | `--config` | |

| debug mode | No | Bool | `DEBUG` | | debug |

| output type | No(default: 'json') | String(json or go-template) | `OUTPUT_TYPE` | `--output` | outputType |

| Go template file path | No(Yes if output type is go-template) | String | `TEMPLATE` | `--template` | template |

| destination type | No(default: 'stdout') | String(stdout or esa) | `DESTINATION` | `--destination` | destination |

| esa's post number for reporting results | No(Yes if destination type is esa) | Number | | | esa.reportPostNumber |

| outdated threshold | No | Number | `OUTDATED_THRESHOLD` | `--outdated-threshold` | outdatedThreshold |

| enable simple text format for annotation | No | Bool | `WITH_SIMPLE_FORMAT` | `--with-simple-format` | withSimpleFormat |

Priority: CLI arguments > Environment variables > Config file

## How to use esa-freshness-patroller as Go module

```

$ go get github.com/kanata2/esa-freshness-patroller/patroller

```