From f92ca810b4f3304d50cdb40178f263d71b3fc7fd Mon Sep 17 00:00:00 2001 From: marekzan Date: Mon, 3 Feb 2025 17:20:55 +0100 Subject: [PATCH] restructure docs for a better readability --- .gitignore | 1 + README.md | 55 ++++++------------- ROADMAP.md | 61 --------------------- examples/CONFIG.md => docs/artifacts.md | 73 ++----------------------- docs/config.md | 36 ++++++++++++ docs/notifiers.md | 56 +++++++++++++++++++ docs/whats_working.md | 32 +++++++++++ 7 files changed, 145 insertions(+), 169 deletions(-) delete mode 100644 ROADMAP.md rename examples/CONFIG.md => docs/artifacts.md (53%) create mode 100644 docs/config.md create mode 100644 docs/notifiers.md create mode 100644 docs/whats_working.md diff --git a/.gitignore b/.gitignore index 00da19b..9c42184 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ integrations.txt /config-offline.json /.env +*.local.* diff --git a/README.md b/README.md index 8f6d8a9..0dac4e3 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,24 @@ # **Veno** -πŸ“’ **VE**rsion **NO**tifier – Stay updated with the latest versions of your essential software! +**VE**rsion **NO**tifier – Stay updated with the latest versions of your essential software! [![GitHub Release](https://img.shields.io/github/v/release/marekzan/veno)](https://github.com/marekzan/veno/releases) [![License](https://img.shields.io/badge/license-Apache%202.0%20or%20MIT-blue.svg)](./LICENSE) -## πŸš€ **Overview** +## **Overview** Veno is a lightweight tool that tracks new versions of software packages and notifies you via email, webhooks, or chat integrations. Define **artifacts** in a simple config file and attach multiple **notifiers**β€”Veno will do the rest! -## πŸ” **How It Works** +## **How It Works** 1. Define software packages (**artifacts**) in `config.json`. 2. Choose notification methods (**notifiers**) like email, Slack, or webhooks. 3. Run Veno via CLI or Web Service to get version updates. -## πŸ“¦ **Artifacts** - -Artifacts represent the software packages you want to track. Veno currently supports: -| Source | Status | -|------------|---------| -| **GitHub** | βœ… Supported | -| **Dockerhub** | βœ… Supported | -| **ArtifactHub** | βœ… Supported | -| **GitLab** | πŸ”œ Planned | -| **Bitbucket** | πŸ”œ Planned | - -## πŸ”” **Notifiers** - -Choose how to receive notifications: -| Notifier | Status | -|------------|--------| -| **Email** | βœ… Supported | -| **Webhook** | βœ… Supported | -| **Google Chat** | 🚧 Basic support | -| **Slack** | 🚧 Basic support | -| **Microsoft Teams** | πŸ”œ Planned | - -## βš™οΈ **Usage** - -Veno supports three operation modes: -| Mode | Status | Description | -|------|--------|-------------| -| **CLI** | βœ… Working | Run checks on demand | -| **Web Service** | 🚧 In Progress | REST API for version tracking | -| **Daemon** | πŸ”œ Planned | Automated background scheduling | +> [!Note] +> See what is currently supported [here](docs/whats_working.md). + +## How to Run **Build it** @@ -58,20 +32,23 @@ You find the binary in `target/release/veno-cli`. veno-cli --config path/to/config.json ``` -## πŸ”§ **Configuration** +> [!Tip] +> We recommend to use the binary as a cron job (or any other scheduling task manager) in your cluster, so you can get the updates in the right time. + +## **Configuration** -All modes require a `config.json` file. Example configuration can be found [here](examples/CONFIG.md). +All modes require a `config.json` file. Example configuration can be found [here](docs/config.md). You can also set values using environment variables via the `${}` syntax. -## πŸ›€οΈ **Features & Roadmap** +## **Features & Roadmap** -For upcoming features, check the [roadmap](ROADMAP.md). +For upcoming features, check the [Issues](https://github.com/marekzan/veno/issues?q=is%3Aissue%20state%3Aopen%20label%3Afeature%2Crefactor) or the [Milestones](https://github.com/marekzan/veno/milestones) -## πŸ’‘ **Contributing** +## **Contributing** Contributions are welcome! Fork the repository and submit a pull request. -## πŸ“ **License** +## **License** Veno is dual-licensed under: diff --git a/ROADMAP.md b/ROADMAP.md deleted file mode 100644 index e4329a8..0000000 --- a/ROADMAP.md +++ /dev/null @@ -1,61 +0,0 @@ -# Roadmap and Features - -## Modes - -| **Status** | **Features** | -| -------------- | ------------ | -| βœ… Supported | cli | -| 🚧 In Progress | web | -| πŸ”œ Planned | daemon | - -## Sources - -| Status | Features | -| ------------ | ----------- | -| βœ… Supported | GitHub | -| βœ… Supported | Artifacthub | -| βœ… Supported | Docker Hub | -| πŸ”œ Planned | GitLab | -| πŸ”œ Planned | Bitbucket | -| πŸ”œ Planned | Quay | - -## Sinks - -| Status | Features | -| ---------------- | --------------- | -| βœ… Supported | Generic Webhook | -| βœ… Supported | Email | -| 🚧 Basic support | Slack | -| 🚧 Basic support | Google Chat | -| πŸ”œ Planned | Microsoft Teams | -| πŸ”œ Planned | Rocket Chat | - -## Features - -| Status | Features | -| ------------ | ------------------------------------ | -| βœ… Supported | multiple notifiers for a sink | -| βœ… Supported | environment variables in config file | -| βœ… Supported | multiple recipients for email sink | - -## Ideas - -| Status | Features | -| ---------- | ------------------------------------------------------------------------------------------------------------------------- | -| πŸ”œ Planned | make notifiers have references to artifacts so that only one message is being sent to the sink for multiple artifacts | -| πŸ”œ Planned | yaml config support | -| πŸ”œ Planned | toml config support | -| πŸ”œ Planned | implement a config linter (check if notifiers, sources and references are valid) | -| πŸ”œ Planned | Web endpoint to silence notifications for a specific artifact | -| πŸ”œ Planned | update the current_version field in the configuration file automatically | -| πŸ”œ Planned | decide on which version update you want to be notified (major, minor, patch or other version regex) | -| πŸ”œ Planned | include alpha, beta, and release candidate versions and allow users to specify which version to track | -| πŸ”œ Planned | scheduling for periodic checks (daemon mode) | -| πŸ”œ Planned | custom Chat Cards for Sinks (if supported) | -| πŸ”œ Planned | alpha, beta, and release candidate versions | -| πŸ”œ Planned | give Veno a repo address where the config file is located. this allows veno to pull and update the config file. | -| πŸ”œ Planned | multiple config files for different teams (including repos with config files) | -| πŸ”œ Planned | script file template to run commands for veno which runs in a k8s pod | -| πŸ”œ Planned | Be able to split artifact and notifier definitions and merge them. So that different teams can maintain their own configs | -| πŸ”œ Planned | Make the version logic more robust (own crate; schema detection; schema logic, etc.) | -| πŸ”œ Planned | Option to also notify with the changelog or just the link to the changelog | diff --git a/examples/CONFIG.md b/docs/artifacts.md similarity index 53% rename from examples/CONFIG.md rename to docs/artifacts.md index 19dc0c6..b002ac4 100644 --- a/examples/CONFIG.md +++ b/docs/artifacts.md @@ -1,14 +1,6 @@ -# Example Config +# Artifacts -```{ - "artifacts": [], - "notifiers": [] -} -``` - -## Artifacts - -### GitHub +## GitHub For the identifier value you just take the part of the url with the `username/reponame` @@ -25,7 +17,7 @@ For the identifier value you just take the part of the url with the `username/re }, ``` -### Artifacthub +## Artifacthub For the identifier value you just take the part of the url with the `kind/organization/packagename` @@ -42,7 +34,7 @@ For the identifier value you just take the part of the url with the `kind/organi }, ``` -### Dockerhub +## Dockerhub For the identifier value you just take the part of the url with the `username/imagename`. Official images have a special syntax `_/nginx` for example. For these you just use the image name `nginx`. @@ -59,60 +51,3 @@ Official images have a special syntax `_/nginx` for example. For these you just "notifier": ["private_email"] } ``` - -## Notifiers - -### Email - -``` -{ - "name": "private_email", - "sink": { - "type": "email", - "host": "smtp.gmail.com", - "port": 587, // optional - default: 587 - "username": "username", - "password": "${EMAIL_PASSWORD}", - "to": "recipient@somemail.com", - "subject": "New version available" // optional - default: "New version available" - } -} -``` - -### Webhook - -The webhook value is just the `url` to the webhook. `Slack` and `Google Chat` use the webhook logic under the hood but they will offer a default chat card in the future. - -``` -{ - "name": "generic_webhook", - "sink": { - "type": "webhook", - "webhook": ".." - } -} -``` - -### Slack - -``` -{ - "name": "team_slack", - "sink": { - "type": "slack", - "webhook": ".." - } -} -``` - -### Google Chat - -``` -{ - "name": "team_google_chat", - "sink": { - "type": "google_chat", - "webhook": "..." - } -} -``` diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000..954248b --- /dev/null +++ b/docs/config.md @@ -0,0 +1,36 @@ +```json +{ + "artifacts": [ + { + "name": "Rust", + "current_version": "1.82.0", + "source": { + "type": "github", + "identifier": "rust-lang/rust" + }, + "notifier": ["private_email", "google_chat"] + } + ], + "notifiers": [ + { + "name": "private_email", + "sink": { + "type": "email", + "host": "smtp.gmail.com", + "port": 587, + "username": "${EMAIL_USERNAME}", + "password": "${EMAIL_PASSWORD}", + "to": ["my_email@account.com"], + "subject": "New version of" + } + }, + { + "name": "team_google_chat", + "sink": { + "type": "google_chat", + "webhook": "https://google_chat.com/webhook" + } + } + ] +} +``` diff --git a/docs/notifiers.md b/docs/notifiers.md new file mode 100644 index 0000000..df4eda7 --- /dev/null +++ b/docs/notifiers.md @@ -0,0 +1,56 @@ +# Notifiers + +## Email + +``` +{ + "name": "private_email", + "sink": { + "type": "email", + "host": "smtp.gmail.com", + "port": 587, // optional - default: 587 + "username": "username", + "password": "${EMAIL_PASSWORD}", + "to": "recipient@somemail.com", + "subject": "New version available" // optional - default: "New version available" + } +} +``` + +## Webhook + +The webhook value is just the `url` to the webhook. `Slack` and `Google Chat` use the webhook logic under the hood but they will offer a default chat card in the future. + +``` +{ + "name": "generic_webhook", + "sink": { + "type": "webhook", + "webhook": ".." + } +} +``` + +## Slack + +``` +{ + "name": "team_slack", + "sink": { + "type": "slack", + "webhook": ".." + } +} +``` + +## Google Chat + +``` +{ + "name": "team_google_chat", + "sink": { + "type": "google_chat", + "webhook": "..." + } +} +``` diff --git a/docs/whats_working.md b/docs/whats_working.md new file mode 100644 index 0000000..19fc6f2 --- /dev/null +++ b/docs/whats_working.md @@ -0,0 +1,32 @@ +# Features + +## Modes + +| **Status** | **Features** | +| ------------ | ------------ | +| βœ… Supported | cli | + +## Sources + +| Status | Features | +| ------------ | ----------- | +| βœ… Supported | GitHub | +| βœ… Supported | Artifacthub | +| βœ… Supported | Docker Hub | + +## Sinks + +| Status | Features | +| ---------------- | --------------- | +| βœ… Supported | Generic Webhook | +| βœ… Supported | Email | +| 🚧 Basic support | Slack | +| 🚧 Basic support | Google Chat | + +## Features + +| Status | Features | +| ------------ | ------------------------------------ | +| βœ… Supported | multiple notifiers for a sink | +| βœ… Supported | environment variables in config file | +| βœ… Supported | multiple recipients for email sink |