Skip to content

docs(readme): add Quick Start; tooling and Docker setup; contribution udates #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hyp3rd merged 1 commit into from
Jan 9, 2026
Merged

docs(readme): add Quick Start; tooling and Docker setup; contribution udates #29

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 53 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,25 +137,66 @@ func main() {

## Documentation

- Detailed usage and behavior notes: `docs/usage.md`
- Security checklist: `docs/security-checklist.md`
- Detailed usage and behavior notes: [Usage](docs/usage.md)
- A quick reference for teams using sectools in production: [Security checklist](docs/security-checklist.md)

## Development

```bash
make test
make lint
make sec
```
### Quick Start

1. Clone and set your module name

```bash
git clone https://github.com/hyp3rd/starter.git my-new-project
Copy link

Copilot AI Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
git clone https://github.com/hyp3rd/starter.git my-new-project
git clone https://github.com/hyp3rd/sectools.git my-new-project

Copilot uses AI. Check for mistakes.
cd my-new-project
./setup-project.sh --module github.com/your/module
Copy link

Copilot AI Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.
```

1. Install toolchain (core). Proto tools stay optional.

```bash
make prepare-toolchain
# If you need proto/gRPC/OpenAPI
PROTO_ENABLED=true make prepare-proto-tools
```

1. Run quality gates and sample app

```bash
make lint
make test
make run # serves /health on HOSTNAME:PORT (defaults localhost:8000)
Copy link

Copilot AI Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.
```

1. Optional: Docker and Compose

```bash
cp .env.example .env # shared runtime config for compose/requests
docker build -t starter-app .
docker compose up --build
```
Comment on lines +173 to +177
Copy link

Copilot AI Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
```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.

Copilot uses AI. Check for mistakes.

### Make Targets (high level)

- `prepare-toolchain` — install core tools (gci, gofumpt, golangci-lint, staticcheck, govulncheck, gosec)
- `prepare-proto-tools` — install buf + protoc plugins (optional, controlled by PROTO_ENABLED)
- `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`
Copy link

Copilot AI Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.

## Contribution Notes

## Contributing
- Tests required for changes; run `make lint test` before PRs.
- Suggested branch naming: `feat/<scope>`, `fix/<scope>`, `chore/<scope>`.
- Update docs when altering tooling, Make targets, or setup steps.

See `CONTRIBUTING.md` for guidelines.
Follow the [contributing guidelines](./CONTRIBUTING.md).

## Code of Conduct
### Code of Conduct

See `CODE_OF_CONDUCT.md`.
Make sure you [observe the Code of Conduct](CODE_OF_CONDUCT.md).
Copy link

Copilot AI Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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".

Suggested change
Make sure you [observe the Code of Conduct](CODE_OF_CONDUCT.md).
Make sure you [observe the Code of Conduct](./CODE_OF_CONDUCT.md).

Copilot uses AI. Check for mistakes.

## License

GPL-3.0. See `LICENSE` for details.
GPL-3.0. See [LICENSE](./LICENSE) for details.
Loading