Skip to content

Commit 4ddd0ed

Browse files
bashSunny101bashSunny101
committed
feat: comprehensive developer experience improvements (issue #68)
- Add VS Code devcontainer for consistent dev environment - Add comprehensive troubleshooting guide with platform-specific solutions - Add error handling documentation for common scenarios - Enhance Makefile with demo, health-check, and clean targets - Improve docker-compose files with realistic multi-service setup - Add CCA demo docker-compose and README - Update CONTRIBUTING.md with detailed workflow and guidelines - Expand README with comprehensive quick-start instructions Addresses all major requirements from issue #68: - Setup automation and validation - Health checks for services - Documentation gaps filled - Improved developer experience with devcontainer - CI validation via GitHub Actions - Platform-specific troubleshooting matrix - One-command demo orchestration Signed-off-by: Sunny <[email protected]>
1 parent 5110c72 commit 4ddd0ed

File tree

11 files changed

+898
-55
lines changed

11 files changed

+898
-55
lines changed

‎.devcontainer/devcontainer.json‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"name": "Veraison Docs Development",
3+
"image": "mcr.microsoft.com/devcontainers/base:ubuntu-22.04",
4+
"features": {
5+
"ghcr.io/devcontainers/features/docker-in-docker:2": {},
6+
"ghcr.io/devcontainers/features/go:1": {
7+
"version": "1.21"
8+
},
9+
"ghcr.io/devcontainers/features/python:1": {
10+
"version": "3.10"
11+
}
12+
},
13+
"customizations": {
14+
"vscode": {
15+
"extensions": [
16+
"ms-python.python",
17+
"golang.go",
18+
"timonwong.shellcheck",
19+
"redhat.vscode-yaml"
20+
]
21+
}
22+
},
23+
"postCreateCommand": "sudo apt-get update && sudo apt-get install -y protobuf-compiler shellcheck curl make && chmod +x scripts/*.sh",
24+
"remoteUser": "vscode"
25+
}

‎CONTRIBUTING.md‎

Lines changed: 146 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -4,25 +4,149 @@ Thank you for your interest in contributing to the Veraison docs. This file give
44
lightweight, focused workflow that helps maintainers review contributions quickly and
55
ensures a consistent developer experience.
66

7-
Steps
8-
1. Fork the repository and create a branch named `docs/issue-<number>-<short-desc>`.
9-
2. Make small, focused commits. Prefer one logical change per commit.
10-
3. Run the provided scripts in `scripts/` to validate your environment and examples.
11-
- `scripts/setup.sh` to install developer prerequisites (non-destructive; prompts before changes).
12-
- `scripts/validate-setup.sh` to run pre-flight checks.
13-
- `scripts/quick-start.sh` to run a minimal local demo (requires Docker).
14-
4. Update or add documentation under the appropriate folder (e.g., `api/`, `demo/`, `architecture/`).
15-
5. Add tests or checks where appropriate (examples validation, OpenAPI linting).
16-
6. Push your branch and open a Pull Request against `main` with the issue number in the title.
17-
18-
Pull Request Checklist
19-
- [ ] I followed the contributing guidelines in this file.
20-
- [ ] I ran `scripts/validate-setup.sh` and fixed any issues.
21-
- [ ] The changes are described clearly in the PR description.
22-
- [ ] If the change affects examples or code, I added or updated tests where applicable.
23-
24-
Notes
25-
- Keep changes minimal and avoid large refactors in the same PR.
26-
- If your change needs CI additions (workflows), open a separate PR for the CI work.
27-
28-
If you have questions, ask on the Veraison Zulip: https://veraison.zulipchat.com
7+
## Getting Started
8+
9+
### Prerequisites
10+
11+
1. Validate your environment:
12+
```bash
13+
make validate
14+
```
15+
16+
2. Install missing dependencies:
17+
```bash
18+
./scripts/setup.sh
19+
```
20+
21+
3. (Optional) Use VS Code devcontainer for a pre-configured environment
22+
23+
### Development Workflow
24+
25+
1. **Fork and Branch**
26+
- Fork the repository
27+
- Create a branch named `docs/issue-<number>-<short-desc>`
28+
- Example: `docs/issue-68-onboarding-scripts`
29+
30+
2. **Make Changes**
31+
- Make small, focused commits (one logical change per commit)
32+
- Update or add documentation under appropriate folders:
33+
- `api/` - API specifications
34+
- `demo/` - Demo walkthroughs
35+
- `architecture/` - Architecture documentation
36+
- `scripts/` - Automation scripts
37+
38+
3. **Validate Changes**
39+
- Run validation: `make validate`
40+
- Run linting: `make shellcheck` (if modifying scripts)
41+
- Test demos: `make demo-psa` or `make demo-cca`
42+
- Run health checks: `make health-check`
43+
44+
4. **Test Documentation**
45+
- Verify all commands work as documented
46+
- Test on your platform (Ubuntu/macOS/Windows WSL)
47+
- Check links and formatting
48+
49+
5. **Submit PR**
50+
- Push your branch
51+
- Open a Pull Request against `main`
52+
- Include issue number in title: `docs: improve setup automation (issue #68)`
53+
- Fill out the PR checklist
54+
55+
## Pull Request Checklist
56+
57+
Before submitting your PR, ensure:
58+
59+
- [ ] I followed the contributing guidelines in this file
60+
- [ ] I ran `make validate` and fixed any issues
61+
- [ ] I ran `make shellcheck` (if scripts were modified)
62+
- [ ] I tested the changes on my platform
63+
- [ ] The changes are described clearly in the PR description
64+
- [ ] I updated relevant documentation (README, TROUBLESHOOTING, etc.)
65+
- [ ] If adding examples, I verified they work correctly
66+
- [ ] I checked for broken links and formatting issues
67+
68+
## Development Environment
69+
70+
### Using Makefile
71+
72+
```bash
73+
make help # Show all available targets
74+
make validate # Validate environment
75+
make shellcheck # Lint shell scripts
76+
make demo-psa # Start PSA demo
77+
make demo-cca # Start CCA demo
78+
make health-check # Check service health
79+
make clean # Stop all services
80+
```
81+
82+
### Using Devcontainer
83+
84+
1. Install VS Code and the "Dev Containers" extension
85+
2. Open this repository in VS Code
86+
3. Press Ctrl+Shift+P and select "Dev Containers: Reopen in Container"
87+
4. The environment will be automatically configured
88+
89+
### Manual Setup
90+
91+
Follow the Quick Start section in [README.md](README.md).
92+
93+
## Contribution Guidelines
94+
95+
### Documentation Style
96+
97+
- Use clear, concise language
98+
- Include code examples where helpful
99+
- Provide platform-specific instructions when needed
100+
- Link to related documentation
101+
- Keep formatting consistent
102+
103+
### Script Guidelines
104+
105+
- Use bash/POSIX shell
106+
- Include usage/help text
107+
- Handle errors gracefully
108+
- Be non-destructive (prompt before changes)
109+
- Test on multiple platforms if possible
110+
111+
### Commit Messages
112+
113+
Follow conventional commit format:
114+
115+
```
116+
type: brief description (issue #N)
117+
118+
Longer explanation if needed
119+
```
120+
121+
Types: `docs`, `feat`, `fix`, `chore`, `test`, `refactor`
122+
123+
Examples:
124+
- `docs: add troubleshooting guide (issue #68)`
125+
- `feat: add health check script (issue #68)`
126+
- `fix: correct docker-compose syntax in PSA demo`
127+
128+
### Testing
129+
130+
- Test all commands and examples
131+
- Verify cross-platform compatibility when possible
132+
- Check that demos start successfully
133+
- Run health checks on services
134+
135+
## Troubleshooting
136+
137+
If you encounter issues:
138+
139+
1. Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common problems
140+
2. Review [docs/ERROR_HANDLING.md](docs/ERROR_HANDLING.md) for error scenarios
141+
3. Ask on [Veraison Zulip](https://veraison.zulipchat.com)
142+
4. Open an issue with detailed information
143+
144+
## Code of Conduct
145+
146+
Be respectful and constructive. We're all here to improve Veraison together.
147+
148+
## Questions?
149+
150+
- Zulip: https://veraison.zulipchat.com
151+
- Issues: https://github.com/veraison/docs/issues
152+
- Discussions: https://github.com/veraison/docs/discussions

‎Makefile‎

Lines changed: 39 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,50 @@
11
SHELL := /bin/bash
2-
.PHONY: validate shellcheck quick-start
2+
.PHONY: help validate shellcheck quick-start demo-psa demo-cca health-check clean
3+
4+
help:
5+
@echo "Veraison Documentation - Available targets:"
6+
@echo " make validate - Run environment validation checks"
7+
@echo " make shellcheck - Run shellcheck on all scripts"
8+
@echo " make quick-start - Run quick-start verification"
9+
@echo " make demo-psa - Start PSA demo services"
10+
@echo " make demo-cca - Start CCA demo services"
11+
@echo " make health-check - Check health of running services"
12+
@echo " make clean - Stop all demo services"
13+
@echo ""
14+
@echo "For troubleshooting, see TROUBLESHOOTING.md"
315

416
validate:
517
@echo "Running project validation..."
6-
./scripts/validate-setup.sh
18+
@./scripts/validate-setup.sh
719

820
shellcheck:
9-
@command -v shellcheck >/dev/null 2>&1 || { echo "shellcheck not found"; exit 2; }
21+
@echo "Running shellcheck on scripts..."
22+
@command -v shellcheck >/dev/null 2>&1 || { echo "shellcheck not found, install it for better validation"; exit 0; }
1023
@shellcheck scripts/*.sh || true
1124

1225
quick-start:
1326
@echo "Quick start (delegates to scripts/quick-start.sh)"
1427
@./scripts/quick-start.sh
28+
29+
demo-psa:
30+
@echo "Starting PSA demo services..."
31+
@cd demo/psa && docker compose up -d
32+
@echo "Services started. Check status with: cd demo/psa && docker compose ps"
33+
34+
demo-cca:
35+
@echo "Starting CCA demo services..."
36+
@cd demo/cca && docker compose up -d
37+
@echo "Services started. Check status with: cd demo/cca && docker compose ps"
38+
39+
health-check:
40+
@echo "Checking service health..."
41+
@./scripts/healthcheck.sh http://localhost:8080/ || echo "PSA verifier not responding"
42+
@./scripts/healthcheck.sh http://localhost:8888/ || echo "PSA provisioning not responding"
43+
@./scripts/healthcheck.sh http://localhost:8081/ || echo "CCA verifier not responding"
44+
@./scripts/healthcheck.sh http://localhost:8889/ || echo "CCA provisioning not responding"
45+
46+
clean:
47+
@echo "Stopping all demo services..."
48+
@cd demo/psa && docker compose down 2>/dev/null || true
49+
@cd demo/cca && docker compose down 2>/dev/null || true
50+
@echo "Services stopped."

‎README.md‎

Lines changed: 54 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -27,31 +27,65 @@
2727
* [Assumptions about Attestation Evidence](musings/token-assumptions.md)
2828
```
2929
30-
## Quick start
30+
## Quick Start
3131
32-
This repository includes small helper scripts to improve the developer onboarding experience
33-
and address common setup/validation tasks. They are intentionally conservative and
34-
platform-guided. See `CONTRIBUTING.md` for the recommended workflow.
32+
This repository includes comprehensive tooling to improve the developer onboarding experience.
33+
See `CONTRIBUTING.md` for the full workflow.
3534
36-
1. Run a quick validation to check your environment:
35+
### 1. Validate Your Environment
3736
38-
```sh
39-
scripts/validate-setup.sh
40-
```
37+
```sh
38+
make validate
39+
# or
40+
scripts/validate-setup.sh
41+
```
42+
43+
### 2. Install Missing Dependencies
44+
45+
```sh
46+
scripts/setup.sh
47+
```
48+
49+
### 3. Run Quick Start
50+
51+
```sh
52+
make quick-start
53+
# or
54+
scripts/quick-start.sh
55+
```
56+
57+
### 4. Start Demo Services
58+
59+
```sh
60+
# PSA demo
61+
make demo-psa
62+
63+
# CCA demo
64+
make demo-cca
65+
66+
# Check health
67+
make health-check
68+
```
69+
70+
### 5. Using VS Code?
71+
72+
Open this repository in a devcontainer for a pre-configured development environment:
73+
- Install the "Dev Containers" extension
74+
- Open Command Palette (Ctrl+Shift+P)
75+
- Select "Dev Containers: Reopen in Container"
76+
77+
### Available Make Targets
4178

42-
2. If tools are missing, either follow the printed suggestions or use the guided setup:
79+
Run `make help` to see all available commands.
4380

44-
```sh
45-
scripts/setup.sh --dry-run
46-
# or
47-
scripts/setup.sh
48-
```
81+
### Troubleshooting
4982

50-
3. To run a minimal quick-start verification (requires Docker):
83+
If you encounter issues, see:
84+
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Platform-specific solutions
85+
- [docs/ERROR_HANDLING.md](docs/ERROR_HANDLING.md) - Common error scenarios
5186

52-
```sh
53-
scripts/quick-start.sh
54-
```
87+
### Demo-Specific Instructions
5588

56-
These scripts are small helpers to make developer onboarding easier. They don't replace
57-
per-demo instructions; please check `demo/` for demo-specific steps (PSA and CCA demos).
89+
For detailed demo walkthroughs:
90+
- PSA: [demo/psa/](demo/psa/)
91+
- CCA: [demo/cca/](demo/cca/)

0 commit comments

Comments
 (0)