lib/awesome-docker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(github): align contributor docs and CI with Go workflow

Browse Source
This commit is contained in:
Julien Bisconti
2026-02-28 00:06:37 +01:00
parent 0f00303939
commit dc01ff137e
9 changed files with 120 additions and 219 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/CODEOWNERS vendored
View File

@@ -1 +1 @@
*.md @veggiemonk @agebhar1 @dmitrytokarev @gesellix @mashb1t @moshloop @vegasbrianc @noteed
* @veggiemonk @agebhar1 @dmitrytokarev @gesellix @mashb1t @moshloop @vegasbrianc @noteed

116
.github/CONTRIBUTING.md vendored
View File

@@ -1,94 +1,56 @@
# Contributing to awesome-docker
First: if you're unsure or afraid of anything, just ask or submit the issue or pull request anyways. You won't be yelled at for giving your best effort. The worst that can happen is that you'll be politely asked to change something. We appreciate any sort of contributions, and don't want a wall of rules to get in the way of that.
Thanks for taking the time to contribute.
However, for those individuals who want a bit more guidance on the best way to contribute to the project, read on. This document will cover what we're looking for. By addressing all the points we're looking for, it raises the chances we can quickly merge or address your contributions.
This repository is a curated list of Docker/container resources plus a Go-based maintenance CLI used by CI. Contributions are welcome for both content and tooling.
We appreciate and recognize [all contributors](https://github.com/veggiemonk/awesome-docker/graphs/contributors).
Please read and follow the [Code of Conduct](./CODE_OF_CONDUCT.md).
Please note that this project is released with a [Contributor Code of Conduct](https://github.com/veggiemonk/awesome-docker/blob/master/.github/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
## What We Accept
# Table of Contents
- New high-quality Docker/container-related projects
- Fixes to descriptions, ordering, or categorization
- Removal of broken, archived, deprecated, or duplicate entries
- Improvements to the Go CLI and GitHub workflows
- [Mission Statement](#mission-statement)
- [Quality Standards](#quality-standards)
- [Contribution Guidelines](#contribution-guidelines)
- [New Collaborators](#new-collaborators)
## README Entry Rules
# Mission Statement
- Use one link per entry.
- Prefer GitHub project/repository URLs over marketing pages.
- Keep entries alphabetically sorted within their section.
- Keep descriptions concise and concrete.
- Use `:construction:` for WIP projects.
- Use `:heavy_dollar_sign:` for paid/commercial services.
- Do not use `:skull:`; archived/deprecated projects should be removed.
- Avoid duplicate links and redirect variants.
`awesome-docker` is a hand-crafted list for high-quality information about Docker and its resources. It should be related or compatible with Docker or containers. If it's just an image built on top of Docker, the project possibly belongs to other [awesome lists](https://github.com/sindresorhus/awesome). You can check the [awesome-selfhosted list](https://github.com/Kickball/awesome-selfhosted) or the [awesome-sysadmin list](https://github.com/n1trux/awesome-sysadmin) as well.
If it's a **tutorial or a blog post**, they get outdated really quickly so we don't really put them on the list but if it is on a very advanced and/or specific topic, we will consider it!
If something is awesome, share it (pull request or [issue](https://github.com/veggiemonk/awesome-docker/issues/new) or [chat](https://gitter.im/veggiemonk/awesome-docker)), let us know why and we will help you!
## Local Validation
# Quality Standards
```bash
# Build CLI
make build
Note that we can help you achieve those standards, just try your best and be brave.
We'll guide you to the best of our abilities.
# Validate README formatting and content
make lint
To be on the list, it would be **nice** if entries adhere to these quality standards:
# Run code tests (when touching Go code)
make test
- It should take less than 20 sec to find what is the project, how to install it and how to use it.
- Generally useful to the community.
- A project on GitHub with a well documented `README.md` file and plenty of examples is considered high quality.
- Clearly stating if an entry is related to (Linux) containers and not to Docker. There is an [awesome list](https://github.com/Friz-zy/awesome-linux-containers) for that.
- Clearly stating "what is it" i.e. which category it belongs to.
- Clearly stating "what is it for" i.e. mention a real problem it solves (even a small one). Make it clear for the next person.
- If it is a **WIP** (work in progress, not safe for production), please mention it. (Remember the time before Docker 1.0 ? ;-) )
- Always put the link to the GitHub project instead of the website!
# Optional: full external checks (requires GITHUB_TOKEN)
./awesome-docker check
./awesome-docker validate
```
To be on the list, the project **must** have:
## Pull Request Expectations
- How to setup/install the project
- How to use the project (examples)
- Keep the PR focused to one logical change.
- Explain what changed and why.
- If adding entries, include the target category.
- If removing entries, explain why (archived, broken, duplicate, etc.).
- Fill in the PR template checklist.
If your PR is not merged, we will tell you why so that you may be able to improve it.
But usually, we are pretty relaxed people, so just come and say hi, we'll figure something out together.
## Maintainer Notes
# Contribution Guidelines
## I want to share a project, what should I do?
- **Adding to the list:** Submit a pull request or open an [issue](https://github.com/veggiemonk/awesome-docker/issues/new)
- **Removing from the list:** Submit a pull request or open an [issue](https://github.com/veggiemonk/awesome-docker/issues/new)
- Changing something else: Submit a pull request or open an [issue](https://github.com/veggiemonk/awesome-docker/issues/new)
- Don't know what to do: Open an [issue](https://github.com/veggiemonk/awesome-docker/issues/new) or join our [chat](https://gitter.im/veggiemonk/awesome-docker), let us know what's going on.
**join the chat:**
[![Join the chat at https://gitter.im/veggiemonk/awesome-docker](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/veggiemonk/awesome-docker)
or you can
**ping us on Twitter:**
* [veggiemonk](https://twitter.com/veggiemonk)
* [idomyowntricks](https://twitter.com/idomyowntricks)
* [gesellix](https://twitter.com/gesellix)
* [dmitrytokarev](https://twitter.com/dmitrytok)
### Rules for Pull Request
- Each item should be limited to one link, no duplicates, no redirection (careful with `http` vs `https`!)
- The link should be the name of the package or project or website
- Description should be clear and concise (read it out loud to be sure)
- Description should follow the link, on the same line
- Entries are listed alphabetically, please respect the order
- If you want to add more than one link, please don't do all PR on the exact same line, it usually results in conflicts and your PR cannot be automatically merged...
Please contribute links to packages/projects you have used or are familiar with. This will help ensure high-quality entries.
#### Your commit message will be a [tweet](https://twitter.com/awesome_docker) so write a [good commit message](https://chris.beams.io/posts/git-commit/), keep that in mind :)
# New Collaborators
If you just joined the team of maintainers for this repo, first of all: WELCOME!
If it is your first time maintaining an open source project, read the [best practice guides for maintainers](https://opensource.guide/best-practices/).
Here are the few things you need to know:
* We don't push directly to the master branch. Every entry **MUST** be reviewed!
* Each entry should be in accordance to this quality standards and contribution guidelines.
* To ask a contributor to make a change, just copy paste this message [here](https://github.com/veggiemonk/awesome-docker/pull/289#issuecomment-285608004) and change few things like names and stuff. **The main idea is to help people making great projects.**
* If something seems weird, i.e. if you don't understand what a project does or the documentation is poor, don't hesitate to (nicely) ask for more explanation (see previous point).
* Say thank you to people who contribute to this project! It may not seems like much but respect and gratitude are important :D
- Changes should be reviewed before merge.
- Prefer helping contributors improve a PR over silently rejecting it.
- Keep `.github` documentation and workflows aligned with current tooling.

9
.github/ISSUE_TEMPLATE/add-a-project.md vendored
View File

@@ -1,18 +1,21 @@
---
name: Add a project
about: Add a new project to the list
title: add [PROJECT_NAME]
title: "add: [PROJECT_NAME]"
labels: pending-evaluation
assignees: ''
---
Category:
Repository link:
Description:
Description (one sentence):
Author:
Why this should be in the list:
Notes (`:construction:` or `:heavy_dollar_sign:` if relevant):
Or directly write it:
```markdown
[REPO](https://github.com/AUTHOR/REPO) - DESCRIPTION. By [@AUTHOR](https://github.com/AUTHOR)
[REPO](https://github.com/AUTHOR/REPO) - DESCRIPTION. By [AUTHOR](https://github.com/AUTHOR)
```

146
.github/MAINTENANCE.md vendored
View File

@@ -1,125 +1,81 @@
# 🔧 Maintenance Guide for Awesome Docker
# Maintenance Guide
This guide helps maintainers keep the awesome-docker list up-to-date and high-quality.
This guide describes how maintainers keep the list and automation healthy.
## 🤖 Automated Systems
## Automated Workflows
### Weekly Health Reports
- **What**: Checks all GitHub repositories for activity, archived status, and maintenance
- **When**: Every Monday at 9 AM UTC
- **Where**: Creates/updates a GitHub issue with label `health-report`
- **Action**: Review the report and mark abandoned projects with `:skull:`
### Pull Requests / Weekly QA (`pull_request.yml`)
### Broken Links Detection
- **What**: Tests all links in README.md for availability
- **When**: Every Saturday at 2 AM UTC + on every PR
- **Where**: Creates/updates a GitHub issue with label `broken-links`
- **Action**: Fix or remove broken links, or add to exclusion list
- Runs on pull requests and weekly on Saturday.
- Builds the Go CLI and runs `./awesome-docker validate`.
### PR Validation
- **What**: Checks for duplicate links and basic validation
- **When**: On every pull request
- **Action**: Automated - contributors see results immediately
### Broken Links Report (`broken_links.yml`)
## 📋 Manual Maintenance Tasks
- Runs weekly on Saturday and on manual trigger.
- Executes `./awesome-docker check`.
- Opens/updates a `broken-links` issue when problems are found.
### Monthly Review (First Monday of the month)
1. Check health report issue for archived/stale projects
2. Mark archived projects with `:skull:` in README.md
3. Review projects with 2+ years of inactivity
4. Remove projects that are truly abandoned/broken
### Weekly Health Report (`health_report.yml`)
### Quarterly Deep Dive (Every 3 months)
1. Run: `./awesome-docker health` then `./awesome-docker report` for detailed report
2. Review project categories - are they still relevant?
3. Check for popular new Docker tools to add
4. Update documentation links if newer versions exist
- Runs weekly on Monday and on manual trigger.
- Executes `./awesome-docker health` then `./awesome-docker report`.
- Opens/updates a `health-report` issue.
### Annual Cleanup (January)
1. Remove all `:skull:` projects older than 1 year
2. Review CONTRIBUTING.md guidelines
3. Update year references in documentation
### Deploy to GitHub Pages (`deploy-pages.yml`)
## 🛠️ Maintenance Commands
- Runs on pushes to `master` and manual trigger.
- Builds website with `./awesome-docker build` and publishes `website/`.
## Day-to-Day Commands
```bash
# Build the CLI
go build -o awesome-docker ./cmd/awesome-docker
# Build CLI
make build
# Lint README formatting (add --fix to auto-fix)
./awesome-docker lint
# README lint/validation
make lint
# Auto-fix formatting issues
./awesome-docker lint --fix
# Check all links (requires GITHUB_TOKEN for GitHub repos)
./awesome-docker check
# PR validation (lint + external link check)
./awesome-docker validate
# Score repository health (requires GITHUB_TOKEN)
./awesome-docker health
# Generate health report from cache
./awesome-docker report
# Build the website
./awesome-docker build
# Run tests
go test ./...
# Link checks and health checks (requires GITHUB_TOKEN)
make check
make health
make report
```
## 📊 Quality Standards
## Content Maintenance Policy
### Adding New Projects
- Must have clear documentation (README with install/usage)
- Should have activity within last 18 months
- GitHub project preferred over website links
- Must be Docker/container-related
- Remove archived/deprecated projects instead of tagging them.
- Remove broken links that cannot be fixed.
- Keep sections alphabetically sorted.
- Keep descriptions short and actionable.
### Marking Projects as Abandoned
Use `:skull:` emoji when:
- Repository is archived on GitHub
- No commits for 2+ years
- Project explicitly states it's deprecated
- Maintainer confirms abandonment
## Suggested Review Cadence
### Removing Projects
Only remove (don't just mark `:skull:`):
- Broken/404 links that can't be fixed
- Duplicate entries
- Spam or malicious projects
- Projects that never met quality standards
### Weekly
## 🚨 Emergency Procedures
- Triage open `broken-links` and `health-report` issues.
- Merge straightforward quality PRs.
### Critical Broken Links
If important resources are down:
1. Check if they moved (update URL)
2. Search for alternatives
3. Check Internet Archive for mirrors
4. Temporarily comment out until resolved
### Monthly
### Spam Pull Requests
1. Close immediately
2. Mark as spam
3. Block user if repeated offense
4. Don't engage in comments
- Review sections for stale/duplicate entries.
- Re-run `check` and `health` manually if needed.
## 📈 Metrics to Track
### Quarterly
- Total projects: ~731 GitHub repos
- Health status: aim for <5% archived
- Link availability: aim for >98% working
- PR merge time: aim for <7 days
- Weekly contributor engagement
- Review `.github` docs and templates for drift.
- Confirm workflows still match repository tooling and policies.
## 🤝 Getting Help
## Contributor Support
- Open a discussion in GitHub Discussions
- Check AGENTS.md for AI assistant guidelines
- Review CONTRIBUTING.md for contributor info
When requesting PR changes, be explicit and actionable:
- point to section/order problems,
- explain why a link should be removed,
- suggest exact wording when description quality is the issue.
---
*Last updated: 2025-10-01*
Last updated: 2026-02-27

58
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

@@ -1,48 +1,28 @@
<!-- Congrats on creating an Awesome Docker entry! 🎉 -->
# Summary
<!-- **Remember that entries are ordered alphabetically** -->
Describe what changed and why.
# TLDR
* all entries sorted alphabetically (from A to Z),
* If paying service add :heavy_dollar_sign:
* If WIP add :construction:
* clear and short description of the project
* project MUST have: How to setup/install
* project MUST have: How to use (examples)
* we can help you get there :)
## Scope
## Quality Standards
- [ ] README entries/content
- [ ] Go CLI/tooling
- [ ] GitHub workflows or `.github` docs
Note that we can help you achieve those standards, just try your best and be brave.
We'll guide you to the best of our abilities.
## If This PR Adds/Edits README Entries
To be on the list, it would be **nice** if entries adhere to these quality standards:
- Category/section touched:
- New or updated project links:
- It should take less than 20 sec to find what is the project, how to install it and how to use it.
- Generally useful to the community.
- A project on GitHub with a well documented `README.md` file and plenty of examples is considered high quality.
- Clearly stating if an entry is related to (Linux) containers and not to Docker. There is an [awesome list](https://github.com/Friz-zy/awesome-linux-containers) for that.
- Clearly stating "what is it" i.e. which category it belongs to.
- Clearly stating "what is it for" i.e. mention a real problem it solves (even a small one). Make it clear for the next person.
- If it is a **WIP** (work in progress, not safe for production), please mention it. (Remember the time before Docker 1.0 ? ;-) )
- Always put the link to the GitHub project instead of the website!
## Validation
To be on the list, the project **must** have:
- [ ] `make lint`
- [ ] `make test` (if Go code changed)
- [ ] `./awesome-docker check` (if `GITHUB_TOKEN` available)
- How to setup/install the project
- How to use the project (examples)
If your PR is not merged, we will tell you why so that you may be able to improve it.
But usually, we are pretty relaxed people, so just come and say hi, we'll figure something out together.
# Rules for Pull Request
- Each item should be limited to one link, no duplicates, no redirection (careful with `http` vs `https`!)
- The link should be the name of the package or project or website
- Description should be clear and concise (read it out loud to be sure)
- Description should follow the link, on the same line
- Entries are listed alphabetically, please respect the order
- If you want to add more than one link, please don't do all PR on the exact same line, it usually results in conflicts and your PR cannot be automatically merged...
Please contribute links to packages/projects you have used or are familiar with. This will help ensure high-quality entries.
## Contributor Checklist
- [ ] Entries are alphabetically ordered in their section
- [ ] Links point to project repositories (no duplicates or redirects)
- [ ] Descriptions are concise and specific
- [ ] Archived/deprecated projects were removed instead of tagged
- [ ] Used `:construction:` and `:heavy_dollar_sign:` only when applicable

2
.github/workflows/broken_links.yml vendored
View File

@@ -17,7 +17,7 @@ jobs:
- uses: actions/setup-go@v5
with:
go-version: "1.22"
go-version-file: go.mod
- name: Build
run: go build -o awesome-docker ./cmd/awesome-docker

2
.github/workflows/deploy-pages.yml vendored
View File

@@ -24,7 +24,7 @@ jobs:
- uses: actions/setup-go@v5
with:
go-version: "1.22"
go-version-file: go.mod
- name: Build CLI
run: go build -o awesome-docker ./cmd/awesome-docker

2
.github/workflows/health_report.yml vendored
View File

@@ -17,7 +17,7 @@ jobs:
- uses: actions/setup-go@v5
with:
go-version: "1.22"
go-version-file: go.mod
- name: Build
run: go build -o awesome-docker ./cmd/awesome-docker

2
.github/workflows/pull_request.yml vendored
View File

@@ -15,7 +15,7 @@ jobs:
- uses: actions/setup-go@v5
with:
go-version: "1.22"
go-version-file: go.mod
- name: Build
run: go build -o awesome-docker ./cmd/awesome-docker