diff --git a/.eslintignore b/.eslintignore new file mode 100644 index 0000000..90ddc01 --- /dev/null +++ b/.eslintignore @@ -0,0 +1,25 @@ +node_modules +dist +build +.next +.vercel +backend +frontend +coverage +*.config.js +*.config.mjs +*.config.ts +.github +docs +examples +templates +k8s +infrastructure +master.sh +*.sh +server +src +extensions +sdk +security +workspace diff --git a/.github/BRANCH_PROTECTION.md b/.github/BRANCH_PROTECTION.md index 6335438..21d6661 100644 --- a/.github/BRANCH_PROTECTION.md +++ b/.github/BRANCH_PROTECTION.md @@ -1,6 +1,7 @@ # GitHub Branch Protection Setup Guide -This document provides instructions for configuring branch protection rules to ensure code quality and security in the Algodons/algo repository. +This document provides instructions for configuring branch protection rules to +ensure code quality and security in the Algodons/algo repository. ## Prerequisites @@ -18,6 +19,7 @@ This document provides instructions for configuring branch protection rules to e ### Step 2: Configure Protection for `main` Branch #### Branch Name Pattern + ``` main ``` @@ -25,6 +27,7 @@ main #### Required Settings **1. Require a pull request before merging** + - ✅ Enable this option - **Required approvals:** 1 (recommended minimum) - ✅ Dismiss stale pull request approvals when new commits are pushed @@ -32,6 +35,7 @@ main - ⚠️ Optional: Require approval of the most recent reviewable push **2. Require status checks to pass before merging** + - ✅ Enable this option - ✅ Require branches to be up to date before merging - **Required status checks:** @@ -46,31 +50,38 @@ main - `Dependency Review` - Dependency vulnerability scan **3. Require conversation resolution before merging** + - ✅ Enable this option (recommended) - Ensures all review comments are addressed **4. Require signed commits** + - ⚠️ Optional but recommended for security - Helps verify commit authenticity **5. Require linear history** + - ⚠️ Optional (prevents merge commits) - Use if you prefer rebase/squash workflow **6. Include administrators** + - ✅ Enable this option (highly recommended) - Applies rules to repository administrators as well **7. Restrict who can push to matching branches** + - ⚠️ Optional - Configure if you want to limit who can push directly - Even with this disabled, PR requirements still apply **8. Allow force pushes** + - ❌ Disable this option (recommended) - Prevents history rewriting **9. Allow deletions** + - ❌ Disable this option (recommended) - Prevents accidental branch deletion @@ -79,18 +90,21 @@ main Repeat Step 2 with the following adjustments: #### Branch Name Pattern + ``` develop ``` #### Recommended Differences + - **Required approvals:** Can be reduced to 1 or even 0 for faster iteration - **Require branches to be up to date:** Can be disabled for faster merges - More relaxed settings appropriate for development branch ## Rulesets (New GitHub Feature) -As an alternative to traditional branch protection rules, GitHub now offers Rulesets which provide more flexibility: +As an alternative to traditional branch protection rules, GitHub now offers +Rulesets which provide more flexibility: ### Creating a Ruleset @@ -99,16 +113,20 @@ As an alternative to traditional branch protection rules, GitHub now offers Rule 3. Configure the following: #### Basic Settings + - **Ruleset Name:** "Production Branch Protection" - **Enforcement status:** Active - **Bypass list:** (empty or specific admin users) #### Target Branches + - **Add target:** `Include by pattern` - **Pattern:** `main` #### Rules + Select the following rules: + - ✅ Restrict deletions - ✅ Require a pull request before merging - Required approvals: 1 @@ -119,18 +137,16 @@ Select the following rules: ## Auto-Approval Configuration -The repository includes an auto-approval workflow (`.github/workflows/auto-approve.yml`) that can automatically approve PRs from trusted contributors. +The repository includes an auto-approval workflow +(`.github/workflows/auto-approve.yml`) that can automatically approve PRs from +trusted contributors. ### Configuring Trusted Contributors Edit `.github/workflows/auto-approve.yml` and update the `TRUSTED_USERS` array: ```yaml -TRUSTED_USERS=( - "owner-username" - "maintainer-username" - "trusted-contributor" -) +TRUSTED_USERS=( "owner-username" "maintainer-username" "trusted-contributor" ) ``` ### Required Permissions @@ -138,7 +154,8 @@ TRUSTED_USERS=( For auto-approval to work, you need to: 1. Create a GitHub App or use a Personal Access Token (PAT) -2. Add the token as a repository secret named `GITHUB_TOKEN` (automatically available) or create a custom secret +2. Add the token as a repository secret named `GITHUB_TOKEN` (automatically + available) or create a custom secret 3. Grant the following permissions: - `pull-requests: write` - `contents: read` @@ -147,12 +164,14 @@ For auto-approval to work, you need to: ⚠️ **Important Security Notes:** -1. **Auto-approval is NOT a replacement for human review** - it's a convenience feature for trusted contributors +1. **Auto-approval is NOT a replacement for human review** - it's a convenience + feature for trusted contributors 2. The workflow still requires: - All CI checks to pass - No security vulnerabilities detected - Clean CodeQL scan -3. Even with auto-approval, we recommend having at least one human reviewer verify changes before merging +3. Even with auto-approval, we recommend having at least one human reviewer + verify changes before merging 4. Consider using auto-approval only for: - Minor documentation updates - Dependency updates (after automated testing) @@ -160,15 +179,19 @@ For auto-approval to work, you need to: ## Required Repository Secrets -Configure the following secrets in **Settings** → **Secrets and variables** → **Actions**: +Configure the following secrets in **Settings** → **Secrets and variables** → +**Actions**: ### Optional Secrets + - `CODECOV_TOKEN` - For code coverage reporting (if using Codecov) - Custom GitHub token if using auto-approval with enhanced permissions ## Notifications Setup -The repository includes a notification workflow (`.github/workflows/pr-notifications.yml`) that: +The repository includes a notification workflow +(`.github/workflows/pr-notifications.yml`) that: + - Notifies reviewers when PRs are opened - Updates on review status changes - Auto-labels PRs based on changed files @@ -192,16 +215,19 @@ After setting up branch protection: ## Troubleshooting ### Status checks not appearing + - Ensure workflows have run at least once - Check that workflow names match exactly - Verify workflows are on the default branch ### Cannot merge even with passing checks + - Verify all required status checks are selected - Check that branch is up to date - Ensure all conversations are resolved ### Auto-approval not working + - Check workflow logs in Actions tab - Verify user is in trusted list - Ensure all CI checks passed @@ -217,6 +243,7 @@ After setting up branch protection: ## Maintenance Review and update these settings: + - **Quarterly:** Review branch protection rules - **After major changes:** Update required status checks - **When adding team members:** Update CODEOWNERS and trusted contributors list diff --git a/.github/CI_CD_DOCUMENTATION.md b/.github/CI_CD_DOCUMENTATION.md index 36ae96e..aa5ba9c 100644 --- a/.github/CI_CD_DOCUMENTATION.md +++ b/.github/CI_CD_DOCUMENTATION.md @@ -1,10 +1,12 @@ # CI/CD Workflows Documentation -This document describes the automated workflows configured for the Algodons/algo repository to ensure code quality, security, and streamlined deployment. +This document describes the automated workflows configured for the Algodons/algo +repository to ensure code quality, security, and streamlined deployment. ## Overview The repository uses GitHub Actions to automate: + - Code linting and formatting checks - Building frontend and backend applications - Running tests @@ -14,50 +16,62 @@ The repository uses GitHub Actions to automate: - Conditional auto-approval for trusted contributors **Note:** Some features require additional configuration: -- **Codecov integration**: Optional - Add `CODECOV_TOKEN` secret for coverage reports + +- **Codecov integration**: Optional - Add `CODECOV_TOKEN` secret for coverage + reports - **Auto-approval**: Optional - Update trusted users list in `auto-approve.yml` -- **CODEOWNERS**: Optional - Replace placeholder team names with actual teams/usernames -- **Bundle size monitoring**: Optional - Requires size-limit configuration (can be added later) +- **CODEOWNERS**: Optional - Replace placeholder team names with actual + teams/usernames +- **Bundle size monitoring**: Optional - Requires size-limit configuration (can + be added later) ## Workflows ### 1. CI Workflow (`ci.yml`) **Triggers:** + - Pull requests to `main` and `develop` branches - Pushes to `main` and `develop` branches **Jobs:** #### Lint Code + - Runs ESLint to check for code quality issues - Runs Prettier to verify code formatting - **Required:** Must pass for PR to be merged #### Build Frontend + - Builds the Vite/React application - Uploads build artifacts for later use - Verifies the frontend can be built successfully #### Build Backend + - Builds the Express server - Uploads build artifacts - Ensures backend code compiles without errors #### Run Tests + - Executes the test suite - Uploads coverage reports to Codecov (if configured) - Validates all tests pass #### TypeScript Type Check + - Runs TypeScript compiler in check mode - Catches type errors without building #### CI Success + - Final check that all jobs completed successfully - **This is the primary status check for branch protection** **Expected Scripts in package.json:** + ```json { "scripts": { @@ -73,28 +87,33 @@ The repository uses GitHub Actions to automate: ### 2. CodeQL Security Scan (`codeql.yml`) **Triggers:** + - Pull requests to `main` and `develop` - Pushes to `main` and `develop` - Scheduled weekly scans (Mondays at 6:00 AM UTC) **Purpose:** + - Identifies security vulnerabilities in JavaScript/TypeScript code - Scans for common security issues (SQL injection, XSS, etc.) - Runs queries from GitHub's security-and-quality query suite **Results:** + - Findings appear in the Security tab under Code scanning alerts - Failed scans will block PR merging if critical issues are found ### 3. Snyk Security Scan (`snyk.yml`) **Triggers:** + - Pull requests to `main` and `develop` - Pushes to `main` and `develop` - Scheduled daily scans (2:00 AM UTC) - Manual workflow dispatch **Purpose:** + - Scans for vulnerabilities in dependencies (npm packages) - Checks Docker container images for security issues - Performs static code analysis for security vulnerabilities @@ -103,30 +122,36 @@ The repository uses GitHub Actions to automate: **Jobs:** #### Snyk Dependency Scan + - Scans npm dependencies for known vulnerabilities - Uploads results to GitHub Security tab - Fails on high severity issues #### Snyk Container Scan + - Builds Docker image - Scans container for vulnerabilities - Only runs on push events and scheduled scans #### Snyk Code Analysis + - Performs static code analysis - Identifies security issues in source code - Checks for common vulnerabilities (XSS, injection, etc.) #### Snyk Monitor (Production) + - Monitors production dependencies - Only runs on pushes to main branch - Tracks vulnerabilities over time in Snyk dashboard **Configuration Required:** + - **SNYK_TOKEN** secret must be configured (see Repository Secrets section) - Get your token from: https://app.snyk.io/account **Results:** + - Findings appear in the Security tab under Code scanning alerts - SARIF files uploaded for integration with GitHub Security - Failed scans will block PR merging if critical issues are found @@ -134,22 +159,26 @@ The repository uses GitHub Actions to automate: ### 4. Automated Code Review (`code-review.yml`) **Triggers:** + - Pull requests opened, synchronized, or reopened **Jobs:** #### ESLint Code Review + - Uses reviewdog to add inline comments on ESLint issues - Only comments on lines that were added in the PR - Provides actionable feedback directly in the PR #### Dependency Review + - Checks for vulnerable dependencies - Analyzes added/updated dependencies - Posts summary in PR comments - Fails on moderate or higher severity vulnerabilities #### Bundle Size Check + - Monitors bundle size changes - Comments on PRs if bundle size increases significantly - Helps prevent performance regressions @@ -157,10 +186,12 @@ The repository uses GitHub Actions to automate: ### 5. Auto-Approve Workflow (`auto-approve.yml`) **Triggers:** + - Pull requests opened, synchronized, or reopened - Only runs for non-draft PRs **Behavior:** + 1. Checks if PR author is in the trusted contributors list 2. Waits for all CI checks to pass 3. Waits for CodeQL scan to complete @@ -169,23 +200,23 @@ The repository uses GitHub Actions to automate: 6. Adds a comment noting auto-approval **Security Safeguards:** + - Only trusted users can receive auto-approval - All CI checks must pass - CodeQL scan must complete without critical findings - Skips auto-approval if security issues are detected -**Configuring Trusted Contributors:** -Edit the `TRUSTED_USERS` array in `.github/workflows/auto-approve.yml`: +**Configuring Trusted Contributors:** Edit the `TRUSTED_USERS` array in +`.github/workflows/auto-approve.yml`: + ```yaml -TRUSTED_USERS=( - "owner-username" - "maintainer-username" -) +TRUSTED_USERS=( "owner-username" "maintainer-username" ) ``` ### 6. PR Notifications (`pr-notifications.yml`) **Triggers:** + - PR opened, reopened, or marked ready for review - Review submitted - Review requested @@ -193,16 +224,21 @@ TRUSTED_USERS=( **Features:** #### Notify Reviewers + - Posts comment when PR is ready for review - Notifies when reviews are submitted - Helps keep team informed #### Auto-Label + Automatically adds labels based on: -- **File types:** `frontend`, `backend`, `tests`, `documentation`, `configuration`, `ci/cd` + +- **File types:** `frontend`, `backend`, `tests`, `documentation`, + `configuration`, `ci/cd` - **Size:** `size/xs`, `size/s`, `size/m`, `size/l`, `size/xl` Label thresholds: + - XS: < 10 lines changed - S: 10-49 lines changed - M: 50-199 lines changed @@ -214,7 +250,9 @@ Label thresholds: ### 1. Repository Configuration #### Required Dependencies + Ensure your `package.json` includes development dependencies for: + ```json { "devDependencies": { @@ -232,7 +270,9 @@ Ensure your `package.json` includes development dependencies for: ``` #### Required Scripts + Add these scripts to `package.json`: + ```json { "scripts": { @@ -252,7 +292,9 @@ Add these scripts to `package.json`: ### 2. Branch Protection Rules -Follow the instructions in [BRANCH_PROTECTION.md](.github/BRANCH_PROTECTION.md) to configure: +Follow the instructions in [BRANCH_PROTECTION.md](.github/BRANCH_PROTECTION.md) +to configure: + - Required status checks - Required approvals - Conversation resolution @@ -261,7 +303,9 @@ Follow the instructions in [BRANCH_PROTECTION.md](.github/BRANCH_PROTECTION.md) ### 3. Repository Secrets (Required & Optional) Configure in Settings → Secrets and variables → Actions: -- `SNYK_TOKEN` - **Required** for Snyk security scanning. Get your token from [Snyk Account Settings](https://app.snyk.io/account) + +- `SNYK_TOKEN` - **Required** for Snyk security scanning. Get your token from + [Snyk Account Settings](https://app.snyk.io/account) - `CODECOV_TOKEN` - Optional for code coverage reporting ### 4. Create Required Labels @@ -269,6 +313,7 @@ Configure in Settings → Secrets and variables → Actions: Create the following labels in your repository (Settings → Labels): **Type Labels:** + - `frontend` - 🎨 Frontend changes - `backend` - ⚙️ Backend changes - `tests` - ✅ Test updates @@ -277,6 +322,7 @@ Create the following labels in your repository (Settings → Labels): - `ci/cd` - 🚀 CI/CD changes **Size Labels:** + - `size/xs` - Extra small changes - `size/s` - Small changes - `size/m` - Medium changes @@ -286,6 +332,7 @@ Create the following labels in your repository (Settings → Labels): ### 5. Update CODEOWNERS Edit `.github/CODEOWNERS` to match your team structure: + ``` * @Algodons/maintainers /src/ @Algodons/frontend-team @@ -297,20 +344,24 @@ Edit `.github/CODEOWNERS` to match your team structure: ### For Contributors 1. **Create a feature branch** + ```bash git checkout -b feature/my-feature ``` 2. **Make changes and commit** + ```bash git add . git commit -m "Add new feature" ``` 3. **Push and create PR** + ```bash git push origin feature/my-feature ``` + Then create a PR on GitHub 4. **Wait for CI checks** @@ -346,6 +397,7 @@ Edit `.github/CODEOWNERS` to match your team structure: ## Monitoring and Maintenance ### Viewing Workflow Runs + - Navigate to the **Actions** tab in GitHub - Select a workflow to view run history - Click on a run to see detailed logs @@ -353,18 +405,23 @@ Edit `.github/CODEOWNERS` to match your team structure: ### Common Issues #### Workflow fails on missing scripts + **Solution:** Add the required scripts to `package.json` #### ESLint errors + **Solution:** Run `npm run lint:fix` locally and commit fixes #### Build failures + **Solution:** Run `npm run build` locally to reproduce and fix #### Type errors + **Solution:** Run `npm run type-check` locally and fix type issues #### Security vulnerabilities + **Solution:** Review CodeQL alerts in Security tab and address findings ### Debugging Workflows @@ -382,11 +439,13 @@ Edit `.github/CODEOWNERS` to match your team structure: ## Performance Considerations ### Workflow Optimization + - Jobs run in parallel where possible - Uses caching for Node.js dependencies - Uploads artifacts for use in subsequent workflows ### Cost Management + - Workflows only run on PR and push events - CodeQL runs weekly to minimize compute usage - Artifacts retained for 7 days @@ -402,12 +461,14 @@ Edit `.github/CODEOWNERS` to match your team structure: ## Continuous Improvement ### Metrics to Track + - Average time from PR creation to merge - Number of failed CI runs - Security vulnerabilities detected and fixed - Test coverage trends ### Regular Reviews + - **Monthly:** Review workflow efficiency - **Quarterly:** Update dependencies and actions versions - **Annually:** Audit security settings and permissions @@ -415,6 +476,7 @@ Edit `.github/CODEOWNERS` to match your team structure: ## Support For issues or questions about CI/CD workflows: + 1. Check workflow logs in the Actions tab 2. Review this documentation 3. Open an issue in the repository diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md index 2656764..6b300c6 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -1,12 +1,15 @@ ## Description + ## Type of Change + - [ ] 🐛 Bug fix (non-breaking change which fixes an issue) - [ ] ✨ New feature (non-breaking change which adds functionality) -- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] 💥 Breaking change (fix or feature that would cause existing functionality + to not work as expected) - [ ] 📝 Documentation update - [ ] 🎨 Style/UI update - [ ] ♻️ Code refactoring @@ -16,19 +19,21 @@ - [ ] 🔒 Security fix ## Related Issues + -Fixes # -Closes # -Related to # + +Fixes # Closes # Related to # ## Changes Made + -- -- -- +- +- +- ## Testing + - [ ] Unit tests pass @@ -37,12 +42,15 @@ Related to # - [ ] Browser testing (if applicable) ### Test Coverage + ## Screenshots/Videos + ## Checklist + - [ ] My code follows the project's style guidelines @@ -55,14 +63,16 @@ Related to # - [ ] Any dependent changes have been merged and published ## Deployment Notes + ## Additional Context + --- -