From ff9c264f4b681844365095094d103f051a4a45f6 Mon Sep 17 00:00:00 2001 From: HueByte Date: Thu, 19 Feb 2026 09:53:06 +0100 Subject: [PATCH] feat: Add documentation files including Code of Conduct, Contributing guidelines, and Security policy; update Markdown linting configuration and scripts --- .gitignore | 3 +- .markdownlint-cli2.jsonc | 41 +++++++----- CODE_OF_CONDUCT.md | 32 ++++++++++ CONTRIBUTING.md | 101 ++++++++++++++++++++++++++++++ README.md | 2 + SECURITY.md | 24 +++++++ docs/api/client-articles/index.md | 10 +++ docs/api/client-articles/toc.yml | 2 + docs/api/core-articles/index.md | 9 +++ docs/api/core-articles/toc.yml | 2 + docs/api/index.md | 17 +++++ docs/api/server-articles/index.md | 11 ++++ docs/api/server-articles/toc.yml | 2 + docs/api/toc.yml | 18 ++++++ docs/docfx.json | 26 ++++++-- docs/images/hue_icon.svg | 2 +- scripts/lint-markdown.sh | 24 +++++++ 17 files changed, 305 insertions(+), 21 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 docs/api/client-articles/index.md create mode 100644 docs/api/client-articles/toc.yml create mode 100644 docs/api/core-articles/index.md create mode 100644 docs/api/core-articles/toc.yml create mode 100644 docs/api/index.md create mode 100644 docs/api/server-articles/index.md create mode 100644 docs/api/server-articles/toc.yml create mode 100644 docs/api/toc.yml create mode 100644 scripts/lint-markdown.sh diff --git a/.gitignore b/.gitignore index d6eb001..886d4b6 100644 --- a/.gitignore +++ b/.gitignore @@ -432,5 +432,4 @@ src/EchoHub.Server/uploads/* # DocFx generated output docs/_site/ -docs/api/ -!docs/api/.gitkeep +docs/_api_meta/ diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index 5b9c36d..1b4e73d 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -1,14 +1,27 @@ -{ - "config": { - "MD013": false, - "MD033": false, - "MD041": false - }, - "ignores": [ - ".dev/**", - "docs/api/**", - "**/node_modules/**", - "**/bin/**", - "**/obj/**" - ] -} +{ + // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md + "config": { + "default": true, + // Allow long lines (common in docs with URLs and code) + "MD013": false, + // Allow duplicate headings in different sections + "MD024": { "siblings_only": true }, + // Allow inline HTML (docfx uses it) + "MD033": false, + // Allow bare URLs + "MD034": false + }, + + "globs": ["**/*.md"], + + "ignores": [ + ".dev/**", + "docs/_site/**", + "docs/api/**", + "node_modules/**", + "**/bin/**", + "**/obj/**", + "publish/**", + ".claude/**" + ] +} diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..18e619b --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,32 @@ +# Code of Conduct + +EchoHub is an open source project. We want it to be a welcoming place for everyone who wants to help. + +## Our standards + +We expect all participants (contributors, reviewers, and maintainers) to: + +- Be respectful and constructive +- Assume good intent and communicate clearly +- Welcome differing viewpoints and experience levels +- Focus on what’s best for the community and the project + +Unacceptable behavior includes: + +- Harassment, discrimination, or personal attacks +- Trolling, insults, or inflammatory comments +- Publishing someone else’s private information (doxxing) +- Sexualized language or unwanted attention + +## Enforcement + +Project maintainers may remove, edit, or reject contributions (issues, comments, PRs) that violate this Code of Conduct. + +## Reporting + +If you experience or witness unacceptable behavior: + +- Use GitHub’s built-in reporting tools where appropriate, and/or +- Contact the project maintainer via GitHub: https://github.com/HueByte + +Please include as much context as you can (links, screenshots, timestamps). Reports will be handled as discreetly as possible. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..59eb129 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,101 @@ +# Contributing to EchoHub + +Thanks for your interest in contributing — EchoHub aims to stay lightweight, terminal-first, and self-hosted. + +## Quick start (dev) + +### Prerequisites + +- .NET 10 SDK + +### Build + +```bash +dotnet build src/EchoHub.slnx +``` + +### Test + +```bash +dotnet test src/EchoHub.slnx +``` + +### Run (local) + +Server: + +```bash +dotnet run --project src/EchoHub.Server +``` + +Client: + +```bash +dotnet run --project src/EchoHub.Client +``` + +## What to work on + +- Check open issues (especially `good first issue` / `help wanted` if present) +- Docs fixes in `docs/` are always welcome +- Tests: `src/EchoHub.Tests/` + +If you’re proposing a larger change, open an issue first so we can align on approach. + +## Code style & expectations + +- Keep PRs focused (small and reviewable) +- Prefer clear naming over cleverness +- Add/adjust tests for bug fixes when it’s practical +- Avoid committing secrets (JWT secrets, tokens, connection strings) + +## Docs + +This repo uses DocFX for the site in `docs/`. + +To build docs locally you typically need the assemblies built in Release first: + +```bash +dotnet build src/EchoHub.slnx --configuration Release +``` + +Then run DocFX: + +```bash +docfx docs/docfx.json +``` + +## Markdown lint + +CI lints Markdown. Locally: + +- On Linux/macOS (or Windows with Git Bash/WSL): + +```bash +./scripts/lint-markdown.sh +``` + +- Anywhere with Node.js installed: + +```bash +npx --yes markdownlint-cli2 +``` + +## Pull requests + +- Fill out the PR template +- Ensure `dotnet test src/EchoHub.slnx` is green +- Mention any behavioral changes (client UX, auth, uploads) + +## Commit messages + +Any consistent style is fine; descriptive subjects help reviews. +Examples: + +- `fix(server): validate image magic bytes` +- `feat(client): add /servers improvements` +- `docs: clarify getting started` + +## Reporting security issues + +Please do **not** file public issues for security problems. See `SECURITY.md`. diff --git a/README.md b/README.md index 1322467..5c91d9f 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +# EchoHub +

EchoHub Logo

diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..19e03cc --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,24 @@ +# Security Policy + +## Reporting a vulnerability + +If you believe you’ve found a security vulnerability in EchoHub (for example: auth bypass, token leakage, file upload validation bypass, RCE, etc.), please **do not** open a public GitHub issue. + +Preferred: use GitHub’s private vulnerability reporting ("Report a vulnerability"): + +- https://github.com/HueByte/EchoHub/security/advisories/new + +If that link is unavailable for your account, contact the maintainer via GitHub: + +- https://github.com/HueByte + +## What to include + +- A clear description of the issue and potential impact +- Reproduction steps or a proof-of-concept +- Affected versions / commit SHA +- Any relevant logs (with secrets removed) + +## Disclosure + +I’ll acknowledge receipt, investigate, and work on a fix. Please avoid publicly disclosing details until a fix is available. diff --git a/docs/api/client-articles/index.md b/docs/api/client-articles/index.md new file mode 100644 index 0000000..7fde157 --- /dev/null +++ b/docs/api/client-articles/index.md @@ -0,0 +1,10 @@ +# Client Articles + +Articles related to the EchoHub TUI client built with Terminal.Gui v2. + +## Topics + +- Terminal.Gui v2 patterns and conventions +- Theme system and customization +- Command system reference +- Configuration management diff --git a/docs/api/client-articles/toc.yml b/docs/api/client-articles/toc.yml new file mode 100644 index 0000000..1ba183c --- /dev/null +++ b/docs/api/client-articles/toc.yml @@ -0,0 +1,2 @@ +- name: Overview + href: index.md diff --git a/docs/api/core-articles/index.md b/docs/api/core-articles/index.md new file mode 100644 index 0000000..852da7d --- /dev/null +++ b/docs/api/core-articles/index.md @@ -0,0 +1,9 @@ +# Core Articles + +Articles related to the EchoHub.Core shared library. + +## Topics + +- Data models and DTOs +- SignalR contract interface +- Validation constants and shared rules diff --git a/docs/api/core-articles/toc.yml b/docs/api/core-articles/toc.yml new file mode 100644 index 0000000..1ba183c --- /dev/null +++ b/docs/api/core-articles/toc.yml @@ -0,0 +1,2 @@ +- name: Overview + href: index.md diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..ae3e487 --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,17 @@ +# API Reference + +Browse the generated API documentation for each EchoHub project. + +## Projects + +### [Client](client/EchoHub.Client.yml) + +Terminal.Gui v2 TUI application -- UI components, services, themes, and configuration. + +### [Core](core/EchoHub.Core.Constants.yml) + +Shared library -- DTOs, models, constants, and the SignalR client contract. + +### [Server](server/EchoHub.Server.Controllers.yml) + +ASP.NET Core server -- controllers, hubs, authentication, and data access. diff --git a/docs/api/server-articles/index.md b/docs/api/server-articles/index.md new file mode 100644 index 0000000..cafad01 --- /dev/null +++ b/docs/api/server-articles/index.md @@ -0,0 +1,11 @@ +# Server Articles + +Articles related to the EchoHub server built with ASP.NET Core. + +## Topics + +- Authentication and JWT tokens +- SignalR hub and real-time messaging +- File upload and validation +- Rate limiting configuration +- Database schema and migrations diff --git a/docs/api/server-articles/toc.yml b/docs/api/server-articles/toc.yml new file mode 100644 index 0000000..1ba183c --- /dev/null +++ b/docs/api/server-articles/toc.yml @@ -0,0 +1,2 @@ +- name: Overview + href: index.md diff --git a/docs/api/toc.yml b/docs/api/toc.yml new file mode 100644 index 0000000..00dbbc6 --- /dev/null +++ b/docs/api/toc.yml @@ -0,0 +1,18 @@ +- name: Client + items: + - name: API Reference + href: ../_api_meta/client/toc.yml + - name: Articles + href: client-articles/ +- name: Core + items: + - name: API Reference + href: ../_api_meta/core/toc.yml + - name: Articles + href: core-articles/ +- name: Server + items: + - name: API Reference + href: ../_api_meta/server/toc.yml + - name: Articles + href: server-articles/ diff --git a/docs/docfx.json b/docs/docfx.json index 691511b..7e25997 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -8,7 +8,7 @@ "files": ["EchoHub.Core.dll"] } ], - "dest": "api/core", + "dest": "_api_meta/core", "filter": "filterConfig.yml" }, { @@ -18,7 +18,7 @@ "files": ["EchoHub.Server.dll"] } ], - "dest": "api/server", + "dest": "_api_meta/server", "filter": "filterConfig.yml" }, { @@ -28,7 +28,7 @@ "files": ["EchoHub.Client.dll"] } ], - "dest": "api/client", + "dest": "_api_meta/client", "filter": "filterConfig.yml" } ], @@ -36,7 +36,25 @@ "content": [ { "files": ["**/*.{md,yml}"], - "exclude": ["_site/**", "_temp/**"] + "exclude": ["_site/**", "_api_meta/**"] + }, + { + "src": "_api_meta/core", + "dest": "api/core", + "files": ["*.yml", ".manifest"], + "exclude": ["toc.yml"] + }, + { + "src": "_api_meta/server", + "dest": "api/server", + "files": ["*.yml", ".manifest"], + "exclude": ["toc.yml"] + }, + { + "src": "_api_meta/client", + "dest": "api/client", + "files": ["*.yml", ".manifest"], + "exclude": ["toc.yml"] } ], "resource": [ diff --git a/docs/images/hue_icon.svg b/docs/images/hue_icon.svg index 47b53ab..fb3a92e 100644 --- a/docs/images/hue_icon.svg +++ b/docs/images/hue_icon.svg @@ -1,4 +1,4 @@ - + diff --git a/scripts/lint-markdown.sh b/scripts/lint-markdown.sh new file mode 100644 index 0000000..f16d74d --- /dev/null +++ b/scripts/lint-markdown.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash +# +# Lint all Markdown files in the repository. +# Config, globs, and ignores are defined in .markdownlint-cli2.jsonc. +# +# Usage: +# ./scripts/lint-markdown.sh # check +# ./scripts/lint-markdown.sh --fix # auto-fix +# +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)" +cd "$REPO_ROOT" + +# Resolve markdownlint-cli2 binary +if command -v markdownlint-cli2 &>/dev/null; then + LINT_CMD="markdownlint-cli2" +else + LINT_CMD="npx --yes markdownlint-cli2" +fi + +echo "Linting Markdown files..." +$LINT_CMD "$@" +echo "Markdown lint passed."