docs(readme): add Quick Start; tooling and Docker setup; contribution udates#29
docs(readme): add Quick Start; tooling and Docker setup; contribution udates#29
Conversation
… updates - Replace inline doc paths with Markdown links (usage, security checklist, license) - Add step-by-step Quick Start (clone, module init via setup-project.sh) - Document installing core toolchain; optionally enable proto tools via PROTO_ENABLED - Describe running quality gates and sample app (`make lint`, `make test`, `make run` serving /health on localhost:8000) - Add Docker/Compose workflow with `.env`, build, and compose instructions - Summarize high-level Make targets (prepare-toolchain, prepare-proto-tools, init, lint, test/test-race/bench, vet, sec, proto, run, run-container, update-deps/toolchain) - Normalize Contributing and Code of Conduct sections with links Docs-only change in README.md.
There was a problem hiding this comment.
Pull request overview
This pull request updates the README.md to add comprehensive development documentation including a Quick Start guide, Make target descriptions, Docker/Compose instructions, and normalized contribution sections. The changes convert inline documentation paths to Markdown links and add detailed setup instructions for developers.
Key changes:
- Converts inline doc paths to Markdown links for Usage, Security Checklist, and License
- Adds a Quick Start section with step-by-step setup instructions
- Documents Make targets and toolchain installation procedures
- Adds Docker and Compose workflow instructions
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - `init` — run setup-project.sh with current module and install tooling (respects PROTO_ENABLED) | ||
| - `lint` — gci, gofumpt, staticcheck, golangci-lint | ||
| - `test` / `test-race` / `bench` | ||
| - `vet`, `sec`, `proto`, `run`, `run-container`, `update-deps`, `update-toolchain` |
There was a problem hiding this comment.
The Make targets "proto", "run", and "run-container" referenced here do not exist in the Makefile. Only "run-example" exists. These targets should either be added to the Makefile or removed from this documentation list.
| ### Code of Conduct | ||
|
|
||
| See `CODE_OF_CONDUCT.md`. | ||
| Make sure you [observe the Code of Conduct](CODE_OF_CONDUCT.md). |
There was a problem hiding this comment.
The link formatting is inconsistent. Line 198 uses "CODE_OF_CONDUCT.md" without the "./" prefix, while line 194 uses "./CONTRIBUTING.md" and line 202 uses "./LICENSE" with the prefix. For consistency, this should be "./CODE_OF_CONDUCT.md".
| Make sure you [observe the Code of Conduct](CODE_OF_CONDUCT.md). | |
| Make sure you [observe the Code of Conduct](./CODE_OF_CONDUCT.md). |
| 1. Clone and set your module name | ||
|
|
||
| ```bash | ||
| git clone https://github.com/hyp3rd/starter.git my-new-project |
There was a problem hiding this comment.
The repository reference is incorrect. This README is for the "sectools" project (as shown in the title, badges, and go.mod), but this line references cloning "github.com/hyp3rd/starter.git". This should be updated to reference the correct repository URL for the sectools project.
| git clone https://github.com/hyp3rd/starter.git my-new-project | |
| git clone https://github.com/hyp3rd/sectools.git my-new-project |
| ```bash | ||
| git clone https://github.com/hyp3rd/starter.git my-new-project | ||
| cd my-new-project | ||
| ./setup-project.sh --module github.com/your/module |
There was a problem hiding this comment.
The setup-project.sh script referenced here does not exist in the repository. The Makefile does reference this script in the "init" target (line 12), but the script file itself is missing. Either the script needs to be added to the repository, or these Quick Start instructions should be updated to use an alternative setup method.
| ```bash | ||
| make lint | ||
| make test | ||
| make run # serves /health on HOSTNAME:PORT (defaults localhost:8000) |
There was a problem hiding this comment.
The "make run" target does not exist in the Makefile. The Makefile only has a "run-example" target. This instruction will fail if users try to follow it. Additionally, there is no evidence of a sample app that serves /health on localhost:8000 in this sectools library project.
| ```bash | ||
| cp .env.example .env # shared runtime config for compose/requests | ||
| docker build -t starter-app . | ||
| docker compose up --build | ||
| ``` |
There was a problem hiding this comment.
The Docker instructions reference files that do not exist in the repository. There is no .env.example file to copy, no Dockerfile for building the image, and no docker-compose.yml file. The reference to "starter-app" in the docker build command is also inconsistent with the sectools project name.
| ```bash | |
| cp .env.example .env # shared runtime config for compose/requests | |
| docker build -t starter-app . | |
| docker compose up --build | |
| ``` | |
| This repository does not ship Docker or Docker Compose configuration out of the box. | |
| If you need containerization, add your own `Dockerfile` and related configuration | |
| appropriate for your environment, and use the standard Docker/Compose commands to | |
| build and run your image. |
1 participant
make lint,make test,make runserving /health on localhost:8000).env, build, and compose instructionsDocs-only change in README.md.