docs: comprehensive developer experience improvements (issue #68) #69
+1,145
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
bashSunny101
force-pushed
the
docs/issue-68-onboarding-scripts
branch
from
4ddd0ed to
6e52bea
Compare
…aison#68) Signed-off-by: Sunny <77166237+bashSunny101@users.noreply.github.com>
…flow (issue veraison#68) Signed-off-by: Sunny <77166237+bashSunny101@users.noreply.github.com>
) - 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 veraison#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 <77166237+bashSunny101@users.noreply.github.com>
bashSunny101
force-pushed
the
docs/issue-68-onboarding-scripts
branch
from
6e52bea to
f64300c
Compare
The docker-compose-plugin package is not available on all Ubuntu versions in GitHub Actions. Switch to installing docker-compose via pip which is more widely compatible across different Ubuntu versions. Signed-off-by: Sunny <77166237+bashSunny101@users.noreply.github.com>
GitHub Actions runners have Docker pre-installed. The docker-compose pip installation was failing due to old PyYAML compatibility issues. Since our validation scripts only check for tool presence and don't run containers in CI, we can rely on the pre-installed Docker and skip the problematic docker-compose installation. Signed-off-by: Sunny <77166237+bashSunny101@users.noreply.github.com>
GitHub Actions and modern Docker installations use Docker Compose v2 (docker compose plugin) instead of the standalone docker-compose v1. Updated validation to check for both versions and made protoc/shellcheck warnings instead of failures since they're optional tools. Signed-off-by: Sunny <77166237+bashSunny101@users.noreply.github.com>
|
@yogeshbdeshpande kindly review my efforts and changes made, and let me know if any further changes are to be made. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR addresses issue #68 by implementing comprehensive improvements to developer onboarding, automation, validation, and documentation quality for the Veraison documentation repository.
Changes Made
1. Setup Automation & Validation ✅
scripts/setup.sh: Interactive, platform-aware dependency installation guidescripts/validate-setup.sh: Pre-flight environment validationscripts/quick-start.sh: One-command quick-start verificationscripts/healthcheck.sh: HTTP health check utility for servicesMakefile: Centralized automation with targets for validation, demos, and health checks2. Enhanced Validation & Testing ✅
.github/workflows/ci-validate.yml: GitHub Actions workflow for automated validationvalidate,shellcheck,demo-psa,demo-cca,health-check,clean3. Documentation Improvements ✅
CONTRIBUTING.md: Comprehensive contributor workflow with:TROUBLESHOOTING.md: Platform-specific troubleshooting guide covering:docs/ERROR_HANDLING.md: Detailed error handling documentation:README.md: Complete quick-start guide with Makefile usage4. Development Environment Modernization ✅
.devcontainer/devcontainer.json: VS Code devcontainer configurationdemo/psa/docker-compose.yml: Multi-service orchestration for PSA demodemo/cca/docker-compose.yml: Multi-service orchestration for CCA demodemo/psa/README.md: Enhanced with Makefile usage and troubleshooting linksdemo/cca/README.md: New quick-start guide for CCA demoRequirements Coverage (Issue #68)
scripts/setup.sh,scripts/validate-setup.sh,scripts/quick-start.sh,Makefilescripts/healthcheck.sh, GitHub Actions CI workflowCONTRIBUTING.md,TROUBLESHOOTING.md,ERROR_HANDLING.md, enhanced READMEsTesting Performed
make validate- Successfully validates environment (reports missing tools correctly)make help- Shows all available targetsmake shellcheck- Lints all shell scriptsFiles Changed
Added:
.devcontainer/devcontainer.json.github/workflows/ci-validate.ymlCONTRIBUTING.mdTROUBLESHOOTING.mdMakefiledemo/cca/docker-compose.ymldemo/cca/README.mddocs/ERROR_HANDLING.mdscripts/setup.shscripts/validate-setup.shscripts/quick-start.shscripts/healthcheck.shModified:
README.md- Added comprehensive Quick Start sectiondemo/psa/docker-compose.yml- Enhanced with multi-service setupdemo/psa/README.md- Improved with troubleshooting linksHow to Review
git checkout docs/issue-68-onboarding-scripts make help make validateThis pull request introduces a comprehensive developer onboarding and demo orchestration workflow for the Veraison documentation repository. It adds a robust set of tools and documentation for environment validation, demo management, troubleshooting, and contributor guidance. The changes focus on improving usability, automation, and clarity for both new and experienced contributors.
Developer Environment & Tooling
.devcontainer/devcontainer.jsonfor a pre-configured VS Code development environment, including Docker, Go, Python, and recommended extensions.Makefilewith targets for validation, linting, demo orchestration, health checks, and troubleshooting, streamlining common developer tasks.Documentation & Contributor Experience
CONTRIBUTING.mdoutlining prerequisites, workflow, commit conventions, and a PR checklist to standardize contributions and onboarding.README.mdwith a Quick Start guide, troubleshooting links, and demo instructions for improved clarity and accessibility.Demo Orchestration
docker-compose.ymlfiles and README guides for both PSA (demo/psa/) and CCA (demo/cca/) demos, enabling one-command startup and health checks for attestation service demos. [1] [2] [3] [4]Validation & CI
.github/workflows/ci-validate.yml) to automatically validate documentation and scripts on pushes and PRs, ensuring repository health.Troubleshooting & Support
TROUBLESHOOTING.mdcovering setup, Docker, platform-specific, demo, and validation issues, with practical solutions for common problems.