diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..641f2cb --- /dev/null +++ b/.dockerignore @@ -0,0 +1,85 @@ +# Git +.git +.gitignore +.gitattributes + +# CI/CD +.github +.gitlab-ci.yml +.travis.yml +azure-pipelines.yml + +# Python +__pycache__ +*.py[cod] +*$py.class +*.so +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg +.pytest_cache/ +.coverage +.coverage.* +htmlcov/ +.tox/ +.nox/ +.mypy_cache/ +.dmypy.json +dmypy.json +.pyre/ +.ruff_cache/ + +# Virtual environments +.venv +venv/ +ENV/ +env/ +env.bak/ +venv.bak/ +.uv/ + +# IDEs +.vscode/ +.idea/ +*.swp +*.swo +*.sublime-project +*.sublime-workspace + +# OS +.DS_Store +Thumbs.db + +# Documentation +docs/ +*.md +!README.md + +# Tests +tests/ +test/ +*.test.py +*.spec.py + +# Node.js (if applicable) +node_modules/ +npm-debug.log +yarn-error.log + +# Misc +.env +.env.local +*.log diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 5b941ec..f166db1 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1 +1,42 @@ -* @cloudzero/octo +# CODEOWNERS file for CloudZero open source projects +# +# Lines starting with '#' are comments. +# Each line is a file pattern followed by one or more owners. +# Owners can be @usernames, @org/team-names, or email addresses. +# +# For more information, see: +# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +# Default owners for everything in the repo +* @cloudzero/open-source-maintainers + +# Python code +*.py @cloudzero/open-source-maintainers +python/ @cloudzero/open-source-maintainers +pyproject.toml @cloudzero/open-source-maintainers + +# JavaScript/TypeScript code +*.js @cloudzero/open-source-maintainers +*.ts @cloudzero/open-source-maintainers +*.jsx @cloudzero/open-source-maintainers +*.tsx @cloudzero/open-source-maintainers +javascript/ @cloudzero/open-source-maintainers +package.json @cloudzero/open-source-maintainers + +# CI/CD configuration +.github/workflows/ @cloudzero/open-source-maintainers +.github/actions/ @cloudzero/open-source-maintainers + +# Documentation +*.md @cloudzero/open-source-maintainers +docs/ @cloudzero/open-source-maintainers + +# Docker configuration +Dockerfile @cloudzero/open-source-maintainers +docker-compose*.yml @cloudzero/open-source-maintainers +.dockerignore @cloudzero/open-source-maintainers + +# Security and compliance +SECURITY.md @cloudzero/open-source-maintainers +LICENSE @cloudzero/open-source-maintainers +NOTICE @cloudzero/open-source-maintainers diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..bae1456 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,106 @@ +name: Bug Report +description: Report a bug or unexpected behavior +title: "[Bug]: " +labels: ["type: bug"] +body: + - type: markdown + attributes: + value: | + **Please do not report security vulnerabilities here.** + Email [security@cloudzero.com](mailto:security@cloudzero.com) instead. + + Thank you for helping us improve this project! Please fill out the following information. + + - type: textarea + id: description + attributes: + label: Description + description: A clear and concise description of the bug + placeholder: What happened? + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to Reproduce + description: Detailed steps to reproduce the behavior + placeholder: | + 1. Go to '...' + 2. Click on '...' + 3. Scroll down to '...' + 4. See error + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What did you expect to happen? + placeholder: Describe what should have happened + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What actually happened? + placeholder: Describe what actually happened + validations: + required: true + + - type: input + id: version + attributes: + label: Version + description: What version of the project are you using? + placeholder: "e.g., 1.2.3" + validations: + required: true + + - type: input + id: platform + attributes: + label: Platform/Framework Version + description: What platform or framework version are you using? + placeholder: "e.g., Python 3.11, Node.js 20" + + - type: input + id: os + attributes: + label: Operating System + description: What operating system are you using? + placeholder: "e.g., Ubuntu 22.04, macOS 14, Windows 11" + + - type: input + id: cloud + attributes: + label: Cloud Provider + description: What cloud provider and services are you using? + placeholder: "e.g., AWS EKS, GCP, Azure" + + - type: textarea + id: logs + attributes: + label: Logs and Error Messages + description: Please provide relevant log output (redact sensitive information) + render: shell + placeholder: Paste logs here + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Add any other context, screenshots, or information about the problem + placeholder: Any additional information that might help + + - type: checkboxes + id: terms + attributes: + label: Code of Conduct + description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/cloudzero/template-cloudzero-open-source/blob/master/CODE-OF-CONDUCT.md) + options: + - label: I agree to follow this project's Code of Conduct + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..a1fa52a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: CloudZero Support + url: mailto:support@cloudzero.com + about: For usage questions and general support + - name: CloudZero Documentation + url: https://docs.cloudzero.com/ + about: Check our documentation for guides and references diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..8954215 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,85 @@ +name: Feature Request +description: Suggest new functionality for this project +title: "[Feature]: " +labels: ["type: feature"] +body: + - type: markdown + attributes: + value: | + **Please do not report security vulnerabilities here.** + Email [security@cloudzero.com](mailto:security@cloudzero.com) instead. + + Thank you for helping us improve this project! Please describe your feature request. + + - type: textarea + id: problem + attributes: + label: Problem Description + description: What problem would this feature solve? Is your feature request related to a problem? + placeholder: I'm always frustrated when... + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: Describe the solution you'd like to see + placeholder: I would like to see... + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: Have you considered any alternative solutions or workarounds? + placeholder: I have considered... + + - type: textarea + id: benefits + attributes: + label: Benefits + description: Who would benefit from this feature and how? + placeholder: This would help... + + - type: dropdown + id: priority + attributes: + label: Priority + description: How important is this feature to you? + options: + - Low - Nice to have + - Medium - Would be helpful + - High - Critical for my use case + validations: + required: true + + - type: dropdown + id: contribution + attributes: + label: Contribution + description: Are you willing to contribute to implementing this feature? + options: + - Yes, I can submit a PR + - Yes, but I need guidance + - No, but I can help with testing + - No + validations: + required: true + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Add any other context, mockups, or examples about the feature request + placeholder: Any additional information + + - type: checkboxes + id: terms + attributes: + label: Code of Conduct + description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/cloudzero/template-cloudzero-open-source/blob/master/CODE-OF-CONDUCT.md) + options: + - label: I agree to follow this project's Code of Conduct + required: true diff --git a/.github/dependabot.yaml b/.github/dependabot.yaml index 3a50959..2368fad 100644 --- a/.github/dependabot.yaml +++ b/.github/dependabot.yaml @@ -16,3 +16,10 @@ updates: labels: - "auto-approve" open-pull-requests-limit: 5 + - package-ecosystem: "npm" + directory: "/javascript" + schedule: + interval: "weekly" + labels: + - "auto-approve" + open-pull-requests-limit: 5 diff --git a/.github/labels.yml b/.github/labels.yml new file mode 100644 index 0000000..3d6c074 --- /dev/null +++ b/.github/labels.yml @@ -0,0 +1,108 @@ +# GitHub Labels Configuration +# Use github-label-sync or similar tools to apply these labels + +# Type labels +- name: "type: bug" + color: "d73a4a" + description: "Something isn't working" + +- name: "type: feature" + color: "0e8a16" + description: "New feature or request" + +- name: "type: documentation" + color: "0075ca" + description: "Improvements or additions to documentation" + +- name: "type: maintenance" + color: "fbca04" + description: "Maintenance and chores" + +# Priority labels +- name: "priority: critical" + color: "b60205" + description: "Critical priority" + +- name: "priority: high" + color: "d93f0b" + description: "High priority" + +- name: "priority: medium" + color: "fbca04" + description: "Medium priority" + +- name: "priority: low" + color: "0e8a16" + description: "Low priority" + +# Status labels +- name: "status: needs-triage" + color: "d4c5f9" + description: "Needs initial triage and prioritization" + +- name: "status: in-progress" + color: "1d76db" + description: "Work in progress" + +- name: "status: blocked" + color: "b60205" + description: "Blocked by another issue or external factor" + +- name: "status: ready-for-review" + color: "0e8a16" + description: "Ready for code review" + +# Resolution labels +- name: "wontfix" + color: "ffffff" + description: "This will not be worked on" + +- name: "duplicate" + color: "cfd3d7" + description: "This issue or pull request already exists" + +- name: "invalid" + color: "e4e669" + description: "This doesn't seem right" + +# Special labels +- name: "good first issue" + color: "7057ff" + description: "Good for newcomers" + +- name: "help wanted" + color: "008672" + description: "Extra attention is needed" + +- name: "security" + color: "b60205" + description: "Security-related issue" + +- name: "breaking-change" + color: "d93f0b" + description: "Introduces breaking changes" + +- name: "dependencies" + color: "0366d6" + description: "Dependency updates" + +- name: "auto-approve" + color: "0e8a16" + description: "Automatically approved for merge" + +# Component labels (customize for your project) +- name: "component: api" + color: "c2e0c6" + description: "Related to API" + +- name: "component: ui" + color: "c5def5" + description: "Related to user interface" + +- name: "component: ci-cd" + color: "bfd4f2" + description: "Related to CI/CD pipelines" + +- name: "component: docs" + color: "0075ca" + description: "Related to documentation" diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 0000000..3d1fb8f --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,36 @@ +changelog: + exclude: + labels: + - ignore-for-release + - duplicate + - invalid + - wontfix + categories: + - title: 🚀 Features + labels: + - type: feature + - enhancement + - feat + - title: 🐛 Bug Fixes + labels: + - type: bug + - bug + - fix + - title: 📚 Documentation + labels: + - documentation + - docs + - title: 🔧 Maintenance + labels: + - chore + - refactor + - dependencies + - title: 🔒 Security + labels: + - security + - title: ⚠️ Breaking Changes + labels: + - breaking-change + - title: Other Changes + labels: + - "*" diff --git a/.github/workflows/ci-javascript.yml b/.github/workflows/ci-javascript.yml new file mode 100644 index 0000000..886ae9a --- /dev/null +++ b/.github/workflows/ci-javascript.yml @@ -0,0 +1,35 @@ +name: JavaScript CI + +on: + push: + branches: [ main, master ] + pull_request: + branches: [ main, master ] + +jobs: + test: + runs-on: ubuntu-latest + strategy: + matrix: + node-version: ['18', '20', '22'] + + steps: + - uses: actions/checkout@v4 + + - name: Use Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Check formatting with Prettier + run: npm run format:check + + - name: Lint with ESLint + run: npm run lint + + - name: Run tests with coverage + run: npm test -- --coverage --coverageThreshold='{"global":{"lines":60,"branches":60,"functions":60,"statements":60}}' diff --git a/.github/workflows/ci-python.yml b/.github/workflows/ci-python.yml new file mode 100644 index 0000000..87f3c86 --- /dev/null +++ b/.github/workflows/ci-python.yml @@ -0,0 +1,43 @@ +name: Python CI + +on: + push: + branches: [ main, master ] + pull_request: + branches: [ main, master ] + +jobs: + test: + runs-on: ubuntu-latest + strategy: + matrix: + python-version: ['3.11', '3.12', '3.13'] + + steps: + - uses: actions/checkout@v4 + + - name: Install uv + uses: astral-sh/setup-uv@v3 + with: + enable-cache: true + + - name: Set up Python ${{ matrix.python-version }} + run: uv python install ${{ matrix.python-version }} + + - name: Install dependencies + run: uv sync --extra dev + + - name: Check formatting with Ruff + run: uv run ruff format --check . + + - name: Lint with Ruff + run: uv run ruff check . + + - name: Run tests with coverage + run: uv run pytest --cov --cov-report=xml --cov-report=term --cov-fail-under=60 + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v4 + with: + file: ./coverage.xml + fail_ci_if_error: false diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..4211cc2 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,39 @@ +name: CodeQL Security Scan + +on: + push: + branches: [ main, master ] + pull_request: + branches: [ main, master ] + schedule: + - cron: '0 0 * * 1' # Weekly on Monday at midnight + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + permissions: + security-events: write + packages: read + actions: read + contents: read + + strategy: + fail-fast: false + matrix: + language: [ 'python', 'javascript' ] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + languages: ${{ matrix.language }} + + - name: Autobuild + uses: github/codeql-action/autobuild@v3 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 diff --git a/.github/workflows/dependabot-auto-merge.yml b/.github/workflows/dependabot-auto-merge.yml new file mode 100644 index 0000000..b7689d8 --- /dev/null +++ b/.github/workflows/dependabot-auto-merge.yml @@ -0,0 +1,30 @@ +name: Dependabot Auto-Merge + +on: + pull_request: + branches: [ main, master ] + +permissions: + contents: write + pull-requests: write + +jobs: + auto-merge: + runs-on: ubuntu-latest + if: github.actor == 'dependabot[bot]' + + steps: + - name: Check if auto-approve label exists + id: check-label + uses: actions/github-script@v7 + with: + script: | + const labels = context.payload.pull_request.labels.map(l => l.name); + return labels.includes('auto-approve'); + + - name: Enable auto-merge for Dependabot PRs + if: steps.check-label.outputs.result == 'true' + run: gh pr merge --auto --squash "$PR_URL" + env: + PR_URL: ${{ github.event.pull_request.html_url }} + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index d759dc1..15b5aa3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ -# Copyright (c) 2016-2023, CloudZero, Inc. or its affiliates. All Rights Reserved. +# Copyright CloudZero, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 # Direct all questions to support@cloudzero.com @@ -132,6 +132,45 @@ dmypy.json # Pyre type checker .pyre/ +# Ruff +.ruff_cache/ + +# uv +.uv/ +uv.lock + +# Node.js +node_modules/ +.npm/ +.yarn/ +.pnp/ +.pnp.js +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +lerna-debug.log* +package-lock.json +yarn.lock +pnpm-lock.yaml + +# macOS +.DS_Store +.AppleDouble +.LSOverride +*.swp +*.swo +*~ + +# Rust (if supporting Rust projects) +target/ +Cargo.lock + +# Docker +.dockerignore + # IDE Cruft .vscode/ .idea/ +*.sublime-project +*.sublime-workspace diff --git a/CHANGELOG.md b/CHANGELOG.md index 34a3de8..97ea052 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,42 @@ -# Change Log +# Changelog -Resources for generating a changelog: +All notable changes to this project will be documented in this file. -[skywinder/Github-Changelog-Generator](https://github.com/skywinder/Github-Changelog-Generator) - generates a full changelog that overwrites the existing CHANGELOG.md. +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -[hzalaz/wt-oss-milestone-changelog](https://github.com/hzalaz/wt-oss-milestone-changelog) - generates a snippet of Markdown that can be added to a CHANGELOG.md. +## [Unreleased] -[conventional-changelog/conventional-changelog](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-cli) - generates a full changelog based on commit history with the option to append to an existing changelog. \ No newline at end of file +### Added +- Initial project setup + +## [1.0.0] - YYYY-MM-DD + +### Added +- Feature description goes here +- Another feature description + +### Changed +- Description of changes to existing functionality + +### Deprecated +- Description of soon-to-be removed features + +### Removed +- Description of now removed features + +### Fixed +- Description of any bug fixes + +### Security +- Description of vulnerability fixes + +--- + +## Resources for Generating Changelogs + +- [skywinder/Github-Changelog-Generator](https://github.com/skywinder/Github-Changelog-Generator) - generates a full changelog that overwrites the existing CHANGELOG.md +- [conventional-changelog/conventional-changelog](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-cli) - generates a full changelog based on commit history with the option to append to an existing changelog + +[Unreleased]: https://github.com/cloudzero/REPO_NAME/compare/v1.0.0...HEAD +[1.0.0]: https://github.com/cloudzero/REPO_NAME/releases/tag/v1.0.0 diff --git a/CODE-OF-CONDUCT.md b/CODE-OF-CONDUCT.md index 71b3a8f..1283626 100644 --- a/CODE-OF-CONDUCT.md +++ b/CODE-OF-CONDUCT.md @@ -65,7 +65,7 @@ representative at an online or offline event. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at -[INSERT CONTACT METHOD]. +[community@cloudzero.com](mailto:community@cloudzero.com). All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 37ff6fb..c609522 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,48 +1,342 @@ # Contribution -Please read [CloudZero contribution guidelines](https://github.com/cloudzero/open-source-template/blob/master/GENERAL-CONTRIBUTING.md). +Thank you for your interest in contributing! Please read [CloudZero's general contribution guidelines](GENERAL-CONTRIBUTING.md) before getting started. ## Documentation -- PR for docs site update, if needed -- Code-level documentation expectations - - 100% documentation coverage for PRs - - Include links to relevant CloudZero doc pages +All code changes should include appropriate documentation: -## Assets compilation +- **Code-level documentation**: Add docstrings for all public functions, classes, and modules +- **README updates**: Update the README.md if your changes affect installation, usage, or features +- **Docs site**: If this project has external documentation, include a link to the corresponding docs PR +- **CloudZero integration**: Include links to relevant [CloudZero documentation](https://docs.cloudzero.com/) where applicable -Information about compiling CSS, JS, Python, Docker, etc. +**Documentation standards:** +- Aim for 100% documentation coverage for new public APIs +- Use clear, concise language +- Include code examples where helpful +- Document parameters, return values, and exceptions -## Environment setup +## Environment Setup -Link to [README installation](README.md#installation) steps and include anything additional needed to contribute to the project. +### Prerequisites + +Before contributing, ensure you have: +- Python 3.11 or higher (for Python projects) +- [uv](https://docs.astral.sh/uv/) - Fast Python package manager (for Python projects) +- Node.js 18+ and npm (for JavaScript projects) +- Git configured with your GitHub account + +### Initial Setup + +1. Fork the repository on GitHub +2. Clone your fork locally: + ```bash + git clone https://github.com/YOUR_USERNAME/REPO_NAME.git + cd REPO_NAME + ``` + +3. Add the upstream repository: + ```bash + git remote add upstream https://github.com/cloudzero/REPO_NAME.git + ``` + +4. Install dependencies: + + **For Python projects:** + ```bash + # Install uv if you haven't already + curl -LsSf https://astral.sh/uv/install.sh | sh + + # Sync dependencies (creates venv automatically) + uv sync + + # Or install with dev dependencies + uv sync --extra dev + ``` + + **For JavaScript projects:** + ```bash + npm install + ``` + +5. Create a new branch for your changes: + ```bash + git checkout -b feature/your-feature-name + ``` + +For more detailed installation steps, see the [README installation section](README.md#installation). ## Testing +We maintain high test coverage to ensure code quality and prevent regressions. + +### Test Structure + +- Place tests in the `tests/` directory +- Name test files with the pattern `test_*.py` (Python) or `*.test.js` (JavaScript) +- Group related tests in test classes or describe blocks +- Use descriptive test names that explain what is being tested + +### Writing Tests + +**Python testing guidelines:** +- Use `pytest` for all tests +- Follow the Arrange-Act-Assert pattern +- Use fixtures for common test setup +- Mock external dependencies + +**JavaScript testing guidelines:** +- Use Jest or your project's test framework +- Write unit tests for individual functions +- Write integration tests for component interactions +- Maintain test isolation + +### Running Tests + +**Python projects:** +```bash +# Run all tests +uv run pytest + +# Run with coverage +uv run pytest --cov + +# Run specific test file +uv run pytest tests/test_module.py + +# Run specific test +uv run pytest tests/test_module.py::test_function_name +``` + +**JavaScript projects:** +```bash +# Run all tests +npm test + +# Run tests in watch mode +npm test -- --watch + +# Run tests with coverage +npm test -- --coverage +``` + +### Test Coverage Requirements + +- New code should have at least 80% test coverage +- Critical paths should have 100% coverage +- PRs that decrease overall coverage may be rejected unless justified + +## Code Quality Tools + +We use automated tools to maintain code quality and consistency. + +### Python Projects + +**Formatting with Ruff:** +```bash +uv run ruff format . +``` + +**Linting with Ruff:** +```bash +uv run ruff check . +uv run ruff check --fix . # Auto-fix issues +``` + +**Run all checks:** +```bash +# Format, lint, and test +uv run ruff format . && uv run ruff check . && uv run pytest +``` + +### JavaScript Projects + +**Formatting with Prettier:** +```bash +npm run format +``` + +**Linting with ESLint:** +```bash +npm run lint +npm run lint:fix # Auto-fix issues +``` + +**Type checking (if using TypeScript):** +```bash +npm run type-check +``` + +### Pre-commit Hooks + +We recommend using pre-commit hooks to catch issues before committing: + +```bash +# Install pre-commit +pip install pre-commit + +# Install hooks +pre-commit install + +# Run hooks manually +pre-commit run --all-files +``` + +## Code Style Guidelines + +### Python Style + +- Follow [PEP 8](https://pep8.org/) style guidelines +- Use type hints for function signatures +- Maximum line length: 100 characters +- Use meaningful variable and function names +- Write docstrings for all public APIs (Google or NumPy style) +- Code formatting is handled by Ruff formatter (replaces Black) -### Adding tests +**Preferred Python Libraries:** +- **Data manipulation**: Use `polars` (prefer over `pandas`) +- **HTTP client**: Use `httpx` (prefer over `requests`) +- **Data validation**: Use `pydantic` v2 +- **AWS Lambda**: Use `aws-lambda-powertools` (when building Lambda functions) -General information about the test suite and how to format and structure tests. +### JavaScript Style -### Running tests +- Use ES6+ features +- Prefer `const` over `let`, avoid `var` +- Use meaningful variable and function names +- Add JSDoc comments for complex functions +- Follow the project's ESLint configuration -Any additional information needed to run the test suite. Include `bash`-formatted commands like: +### Commit Messages + +Follow [Conventional Commits](https://www.conventionalcommits.org/): + +``` +type(scope): subject + +body (optional) + +footer (optional) +``` + +**Types:** +- `feat`: New feature +- `fix`: Bug fix +- `docs`: Documentation changes +- `style`: Code style changes (formatting, etc.) +- `refactor`: Code refactoring +- `test`: Test changes +- `chore`: Build process or auxiliary tool changes + +**Examples:** +``` +feat(api): add support for new endpoint + +fix(auth): resolve token expiration issue + +docs(readme): update installation instructions +``` + +## Assets Compilation + +### Python Projects + +If your project includes compiled assets: + +```bash +# Build distribution packages +uv build + +# Build Docker images (if applicable) +docker build -t project-name . +``` + +### JavaScript Projects + +If your project requires asset compilation: ```bash -composer test -bundle exec rake test +# Build for production +npm run build + +# Build for development +npm run build:dev + +# Watch mode for development +npm run watch ``` -Also include any information about essential manual tests. +## CI/CD Information + +All PRs must pass continuous integration checks before merging. + +### GitHub Actions Checks + +Our CI pipeline runs: +1. **Linting**: Code style and quality checks +2. **Tests**: Full test suite with coverage reporting +3. **Security scanning**: Dependency vulnerability checks +4. **Build verification**: Ensures project builds successfully + +### Passing CI Checks + +To ensure your PR passes CI: + +1. Run all quality checks locally before pushing +2. Fix any linting errors +3. Ensure all tests pass +4. Maintain or improve test coverage +5. Resolve any security vulnerabilities in dependencies + +If CI fails: +- Review the error logs in GitHub Actions +- Fix issues locally +- Push updates to your branch +- CI will automatically re-run + +## Pull Request Guidelines + +### Before Submitting + +- [ ] Code follows the project's style guidelines +- [ ] All tests pass locally +- [ ] New tests added for new functionality +- [ ] Documentation updated (if applicable) +- [ ] Commit messages follow conventional commits format +- [ ] Branch is up to date with main/master + +### PR Description + +Include in your PR description: +- **Summary**: What changes does this PR introduce? +- **Motivation**: Why are these changes needed? +- **Testing**: How was this tested? +- **Screenshots**: Include screenshots for UI changes +- **Breaking changes**: Clearly mark any breaking changes +- **Related issues**: Link to related GitHub issues + +### Review Process -## Code quality tools +- PRs require at least one approval from maintainers +- Address all reviewer feedback +- Keep PRs focused and reasonably sized +- Be responsive to comments and questions +- Once approved, a maintainer will merge your PR -Information about scripts to run before committing. +## Getting Help -## CI Information +If you need help: +- Check existing [GitHub Issues](../../issues) +- Review the [README](README.md) documentation +- Ask questions in PR comments +- Contact the team at support@cloudzero.com -What CI checks for and how to pass. +## Additional Resources -## Repo-specific PR guidelines +- [CloudZero General Contributing Guidelines](GENERAL-CONTRIBUTING.md) +- [Code of Conduct](CODE-OF-CONDUCT.md) +- [Security Policy](SECURITY.md) +- [CloudZero Documentation](https://docs.cloudzero.com/) -Anything not covered in the general guidelines linked above. \ No newline at end of file +Thank you for contributing to make this project better! \ No newline at end of file diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..01c5e25 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,37 @@ +# Copyright CloudZero, Inc. or its affiliates. All Rights Reserved. +# SPDX-License-Identifier: Apache-2.0 + +# Multi-stage Dockerfile for Python applications +# Adjust as needed for your specific project + +# Build stage +FROM python:3.13-slim as builder + +WORKDIR /app + +# Install uv +COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv + +# Copy dependency files +COPY pyproject.toml ./ +COPY README.md ./ + +# Install dependencies +RUN uv sync --no-dev + +# Runtime stage +FROM python:3.13-slim + +WORKDIR /app + +# Copy virtual environment from builder +COPY --from=builder /app/.venv /app/.venv + +# Copy application code +COPY . . + +# Set PATH to use virtual environment +ENV PATH="/app/.venv/bin:$PATH" + +# Default command (adjust for your application) +CMD ["python", "-m", "your_module"] diff --git a/LICENSE b/LICENSE index 1afe0ca..3cd7595 100644 --- a/LICENSE +++ b/LICENSE @@ -186,7 +186,7 @@ same "printed page" as the copyright notice for easier identification within third-party archives. - Copyright 2023 CloudZero, Inc. + Copyright CloudZero, Inc. or its affiliates. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..01eda6f --- /dev/null +++ b/Makefile @@ -0,0 +1,84 @@ +# Copyright CloudZero, Inc. or its affiliates. All Rights Reserved. +# SPDX-License-Identifier: Apache-2.0 + +.PHONY: help install install-dev test lint format clean build docker-build docker-up docker-down + +# Default target +help: + @echo "Available targets:" + @echo " install - Install production dependencies" + @echo " install-dev - Install development dependencies" + @echo " test - Run tests with coverage" + @echo " lint - Run linting checks" + @echo " format - Format code" + @echo " clean - Remove build artifacts and caches" + @echo " build - Build distribution packages" + @echo " docker-build - Build Docker image" + @echo " docker-up - Start Docker containers" + @echo " docker-down - Stop Docker containers" + +# Python: Install production dependencies +install: + uv sync + +# Python: Install development dependencies +install-dev: + uv sync --extra dev + +# Python: Run tests with coverage +test: + uv run pytest --cov --cov-report=term-missing --cov-report=html + +# Python: Run linting checks +lint: + uv run ruff check . + +# Python: Format code +format: + uv run ruff format . + +# Python: Run all checks (format, lint, test) +check: format lint test + +# Clean build artifacts and caches +clean: + rm -rf build/ dist/ *.egg-info/ + rm -rf .pytest_cache/ .ruff_cache/ .mypy_cache/ + rm -rf htmlcov/ .coverage coverage.xml + find . -type d -name __pycache__ -exec rm -rf {} + + find . -type f -name "*.pyc" -delete + find . -type f -name "*.pyo" -delete + find . -type f -name "*.py,cover" -delete + +# Build Python distribution packages +build: + uv build + +# Docker: Build image +docker-build: + docker build -t template-cloudzero-open-source:latest . + +# Docker: Start containers +docker-up: + docker-compose up -d + +# Docker: Stop containers +docker-down: + docker-compose down + +# Docker: View logs +docker-logs: + docker-compose logs -f + +# JavaScript targets (uncomment if needed) +# npm-install: +# cd javascript && npm install +# +# npm-test: +# cd javascript && npm test +# +# npm-lint: +# cd javascript && npm run lint +# +# npm-format: +# cd javascript && npm run format diff --git a/NOTICE b/NOTICE new file mode 100644 index 0000000..30ad341 --- /dev/null +++ b/NOTICE @@ -0,0 +1,23 @@ +CloudZero Open Source Template +Copyright CloudZero, Inc. or its affiliates. All Rights Reserved. + +This product includes software developed at CloudZero (https://www.cloudzero.com/). + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +--- + +This software contains third-party components. Please see the individual +component licenses in the dependencies for their respective license terms. + +For questions or concerns, please contact: support@cloudzero.com diff --git a/README-template.md b/README-template.md index 9020f6e..c1a0499 100644 --- a/README-template.md +++ b/README-template.md @@ -76,8 +76,8 @@ This section should include basic usage instructions that can be successfully co We appreciate feedback and contribution to this repo! Before you get started, please see the following: -- [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md) -- [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md) +- [CloudZero's general contribution guidelines](GENERAL-CONTRIBUTING.md) +- [CloudZero's code of conduct guidelines](CODE-OF-CONDUCT.md) - [This repo's contribution guide](CONTRIBUTING.md) ## Support + Feedback diff --git a/README.md b/README.md index 9dfa6d5..73386ff 100644 --- a/README.md +++ b/README.md @@ -20,10 +20,10 @@ thank you Auth0, we :heart: you all, and not just because you have a zero in you This repo can be cloned, modified, then re-purposed for new open source projects. It can also be used piecemeal to improve existing repos. -### Copy README-sample.md to README.md +### Copy README-template.md to README.md -The core of open source repo quality is the `README.md` file that's displayed on the repo's homepage in Github. -The `README-sample.md` included here was collaboratively created by CloudZero's engineering team and community +The core of open source repo quality is the `README.md` file that's displayed on the repo's homepage in Github. +The `README-template.md` included here was collaboratively created by CloudZero's engineering team and community engineering team based on samples of high-quality README files around the web. Most sections within this file should be considered required, even if that section contains a link to a more relevant @@ -51,7 +51,7 @@ The issue and PR templates contained in this repo are general guidelines for wha ### Update LICENSE -See `README-sample.md` for guidelines. +See `README-template.md` for guidelines. ### Modify .gitignore diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..4156e73 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,32 @@ +# Security Policy + +## Reporting a Vulnerability + +The CloudZero team takes security issues seriously. We appreciate your efforts to responsibly disclose your findings. + +**Please do not report security vulnerabilities through public GitHub issues.** + +Instead, please report security vulnerabilities by emailing [security@cloudzero.com](mailto:security@cloudzero.com). + +Please include the following information in your report: + +- Type of issue (e.g., buffer overflow, SQL injection, cross-site scripting, etc.) +- Full paths of source file(s) related to the manifestation of the issue +- The location of the affected source code (tag/branch/commit or direct URL) +- Any special configuration required to reproduce the issue +- Step-by-step instructions to reproduce the issue +- Proof-of-concept or exploit code (if possible) +- Impact of the issue, including how an attacker might exploit it + +This information will help us triage your report more quickly. + +## Response Process + +After submitting a vulnerability report, you can expect: + +1. A response acknowledging your report +2. An assessment of the vulnerability and its impact +3. Communication about the fix timeline +4. Credit for your discovery (if desired) when the vulnerability is publicly disclosed + +Thank you for helping keep CloudZero and our users safe! diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..7961181 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,40 @@ +# Copyright CloudZero, Inc. or its affiliates. All Rights Reserved. +# SPDX-License-Identifier: Apache-2.0 + +version: '3.8' + +services: + app: + build: + context: . + dockerfile: Dockerfile + image: template-cloudzero-open-source:latest + container_name: cloudzero-app + environment: + - ENVIRONMENT=development + ports: + - "8000:8000" + volumes: + # Mount source code for development + - .:/app + # Preserve virtual environment + - venv:/app/.venv + command: python -m your_module + restart: unless-stopped + + # Example: Add database service if needed + # db: + # image: postgres:15-alpine + # container_name: cloudzero-db + # environment: + # POSTGRES_DB: mydb + # POSTGRES_USER: user + # POSTGRES_PASSWORD: password + # ports: + # - "5432:5432" + # volumes: + # - db-data:/var/lib/postgresql/data + +volumes: + venv: + # db-data: diff --git a/javascript/.npmignore b/javascript/.npmignore index 1759fd7..099a7f9 100644 --- a/javascript/.npmignore +++ b/javascript/.npmignore @@ -1,20 +1,52 @@ # Docs = https://docs.npmjs.com/misc/developers#keeping-files-out-of-your-package -# -# Commonly-used directives: -# -# .vscode/ -# bin/ -# build/ -# css/ -# coverage/ -# examples/ -# release/ -# scripts/ -# src/ -# support/ -# test/ -# bower.json -# Gruntfile.js -# .css.map -# *~ -# .babelrc \ No newline at end of file + +# Development files +.github/ +.vscode/ +.idea/ +*.sublime-project +*.sublime-workspace + +# Test files +tests/ +test/ +__tests__/ +*.test.js +*.test.ts +*.spec.js +*.spec.ts +coverage/ +.nyc_output/ + +# Build and config files +tsconfig.json +tsconfig.*.json +.eslintrc* +.prettierrc* +.editorconfig +.gitignore +.gitattributes + +# CI/CD +.travis.yml +.gitlab-ci.yml +azure-pipelines.yml +.circleci/ + +# Documentation (unless you want to include it) +docs/ +examples/ +*.md +!README.md + +# Source files (if publishing built files only) +src/ + +# Development dependencies +node_modules/ + +# Misc +.DS_Store +*.log +*.swp +*~ diff --git a/javascript/package.json b/javascript/package.json index fce65a8..e9bf04f 100644 --- a/javascript/package.json +++ b/javascript/package.json @@ -9,8 +9,40 @@ "type": "git", "url": "git://github.com/cloudzero/template-cloudzero-open-source" }, + "bugs": { + "url": "https://github.com/cloudzero/template-cloudzero-open-source/issues" + }, + "homepage": "https://github.com/cloudzero/template-cloudzero-open-source#readme", "main": "index.js", - "scripts": {}, - "devDependencies": {}, + "engines": { + "node": ">=18.0.0", + "npm": ">=9.0.0" + }, + "scripts": { + "test": "jest", + "test:watch": "jest --watch", + "test:coverage": "jest --coverage", + "lint": "eslint .", + "lint:fix": "eslint . --fix", + "format": "prettier --write .", + "format:check": "prettier --check .", + "type-check": "tsc --noEmit", + "build": "tsc", + "build:watch": "tsc --watch", + "clean": "rm -rf dist coverage .eslintcache" + }, + "devDependencies": { + "@types/jest": "^29.5.0", + "@types/node": "^20.0.0", + "@typescript-eslint/eslint-plugin": "^7.0.0", + "@typescript-eslint/parser": "^7.0.0", + "eslint": "^9.0.0", + "eslint-config-prettier": "^9.0.0", + "eslint-plugin-jest": "^28.0.0", + "jest": "^29.7.0", + "prettier": "^3.2.0", + "ts-jest": "^29.1.0", + "typescript": "^5.4.0" + }, "dependencies": {} -} \ No newline at end of file +} diff --git a/python/pyproject.toml b/python/pyproject.toml index 9f12e17..dafe811 100644 --- a/python/pyproject.toml +++ b/python/pyproject.toml @@ -1,9 +1,13 @@ +[build-system] +requires = ["setuptools>=61.0", "wheel"] +build-backend = "setuptools.build_meta" + [project] name = "template-cloudzero-open-source" dynamic = ["version"] description = "CloudZero Open Source Template" readme = "README.md" -requires-python = ">=3.9" +requires-python = ">=3.11" license = {text = "Apache-2.0"} authors = [ { name = "CloudZero", email = "support@cloudzero.com" }, @@ -18,5 +22,109 @@ classifiers = [ "Natural Language :: English", "Operating System :: MacOS", "Operating System :: Unix", - "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", +] + +[project.urls] +Homepage = "https://github.com/cloudzero/template-cloudzero-open-source" +Documentation = "https://github.com/cloudzero/template-cloudzero-open-source#readme" +Repository = "https://github.com/cloudzero/template-cloudzero-open-source" +"Bug Tracker" = "https://github.com/cloudzero/template-cloudzero-open-source/issues" +"Source Code" = "https://github.com/cloudzero/template-cloudzero-open-source" + +[project.optional-dependencies] +dev = [ + "pytest>=8.0", + "pytest-cov>=4.1", + "ruff>=0.3.0", +] +test = [ + "pytest>=8.0", + "pytest-cov>=4.1", +] +lint = [ + "ruff>=0.3.0", +] +# For data-focused projects, prefer polars over pandas +data = [ + "polars>=0.20.0", +] +# For HTTP clients, prefer httpx over requests +http = [ + "httpx>=0.27.0", +] +# For data validation, use pydantic 2 +validation = [ + "pydantic>=2.0", +] +# For AWS Lambda projects, use aws-lambda-powertools +aws-lambda = [ + "aws-lambda-powertools>=2.0", +] + +[tool.pytest.ini_options] +testpaths = ["tests"] +python_files = ["test_*.py"] +python_classes = ["Test*"] +python_functions = ["test_*"] +addopts = [ + "--cov=src", + "--cov-report=term-missing", + "--cov-report=html", + "--cov-report=xml", +] + +[tool.coverage.run] +source = ["src"] +omit = [ + "*/tests/*", + "*/test_*.py", +] + +[tool.coverage.report] +fail_under = 60 +exclude_lines = [ + "pragma: no cover", + "def __repr__", + "raise AssertionError", + "raise NotImplementedError", + "if __name__ == .__main__.:", + "if TYPE_CHECKING:", + "@abstractmethod", +] + +[tool.ruff] +line-length = 100 +target-version = "py311" + +[tool.ruff.format] +quote-style = "double" +indent-style = "space" +line-ending = "auto" + +[tool.ruff.lint] +select = [ + "E", # pycodestyle errors + "W", # pycodestyle warnings + "F", # pyflakes + "I", # isort + "B", # flake8-bugbear + "C4", # flake8-comprehensions + "UP", # pyupgrade +] +ignore = [ + "E501", # line too long, handled by ruff formatter +] + +[tool.ruff.lint.isort] +known-first-party = ["your_package_name"] + +[tool.uv] +dev-dependencies = [ + "pytest>=8.0", + "pytest-cov>=4.1", + "ruff>=0.3.0", ] \ No newline at end of file