1  # Contribution Guidelines
  2  
  3  We welcome contributions to the AI-enhanced CV system! By following these guidelines, you can help ensure the quality, consistency, and maintainability of the project.
  4  
  5  ## Getting Started
  6  
  7  To set up your local development environment, follow these steps:
  8  
  9  1.  **Fork the Repository**: Fork the `adrianwedd/cv` repository to your GitHub account.
 10  2.  **Clone Your Fork**: Clone your forked repository to your local machine:
 11  
 12      ```bash
 13      git clone https://github.com/YOUR_USERNAME/cv.git
 14      cd cv
 15      ```
 16  3.  **Install Dependencies**:
 17      *   **Node.js Dependencies**: Navigate to the `scripts` directory and install the Node.js dependencies:
 18  
 19          ```bash
 20          cd .github/scripts
 21          npm install
 22          cd ../..
 23          ```
 24      *   **Python Dependencies**: Install Python dependencies. If a `requirements.txt` file exists in `src/python/`, use:
 25  
 26          ```bash
 27          pip install -r src/python/requirements.txt
 28          ```
 29          Otherwise, install individual packages as needed (e.g., `pip install requests python-dotenv`).
 30  
 31  4.  **Set up Environment Variables**: The scripts require certain environment variables to function correctly. Create a `.env` file in the project root (or set them in your shell environment):
 32  
 33      ```
 34      GITHUB_TOKEN=your_github_personal_access_token
 35      ANTHROPIC_API_KEY=your_claude_api_key
 36      ABSTRACT_API_KEY=your_abstract_api_key # For Python API wrappers
 37      INTELLIZENCE_API_KEY=your_intellizence_api_key # For Python API wrappers
 38      # Optional: CUSTOM_DOMAIN=your.custom.domain
 39      ```
 40      *   **GitHub Token**: Generate a [GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `repo` scope.
 41      *   **Claude API Key**: Obtain an API key from [Anthropic](https://www.anthropic.com/).
 42  
 43  ## Running Scripts Locally
 44  
 45  You can run the core scripts locally for development and testing:
 46  
 47  *   **Analyze GitHub Activity** (Node.js):
 48  
 49      ```bash
 50      node .github/scripts/activity-analyzer.js
 51      ```
 52  *   **Enhance CV Content with AI** (Node.js):
 53  
 54      ```bash
 55      node .github/scripts/claude-enhancer.js
 56      ```
 57  *   **Generate CV Website** (Node.js):
 58  
 59      ```bash
 60      node .github/scripts/cv-generator.js
 61      ```
 62  *   **Run Python Utilities** (Example):
 63  
 64      ```bash
 65      python src/python/utils/logging_utils.py
 66      ```
 67  
 68  ## Code Style and Linting
 69  
 70  We use ESLint (for JavaScript) and Ruff (for Python) to maintain consistent code style and quality. Please ensure your code adheres to these standards.
 71  
 72  *   **JavaScript Linting**: Check for code quality issues:
 73  
 74      ```bash
 75      cd .github/scripts
 76      npm run lint
 77      ```
 78  *   **Python Linting**: Check for code quality issues (from project root):
 79  
 80      ```bash
 81      ruff check src/python/
 82      ```
 83  *   **Formatting**: Automatically format your code (for JavaScript, from `.github/scripts`):
 84  
 85      ```bash
 86      npm run format
 87      ```
 88  
 89  ## Running Tests
 90  
 91  Unit tests are implemented using Node.js's native test runner (for JavaScript) and Python's `unittest` module (for Python). Please run tests before submitting a pull request.
 92  
 93  *   **Execute JavaScript Tests**:
 94  
 95      ```bash
 96      cd .github/scripts
 97      npm test
 98      ```
 99  *   **Execute Python Tests** (from project root):
100  
101      ```bash
102      python -m unittest discover -s src/python/ -p "test_*.py"
103      ```
104  
105  ## Submitting Pull Requests
106  
107  1.  **Create a New Branch**: Create a new branch for your feature or bug fix:
108  
109      ```bash
110      git checkout -b feature/your-feature-name
111      ```
112  2.  **Make Changes**: Implement your changes, ensuring they adhere to the code style and pass all tests.
113  3.  **Commit Changes**: Write clear, concise commit messages. Follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification (e.g., `feat: Add new feature`, `fix: Resolve bug`).
114  4.  **Push to Your Fork**: Push your changes to your forked repository:
115  
116      ```bash
117      git push origin feature/your-feature-name
118      ```
119  5.  **Create a Pull Request**: Open a pull request from your forked repository to the `main` branch of the upstream `adrianwedd/cv` repository. Provide a clear description of your changes and link to any relevant issues.
120  
121  ## Issue Management
122  
123  This project uses a systematic approach to issue management, guided by the `10x-dev-architect` agent's issue grooming procedure. Please refer to the agent's documentation (`.claude/agents/10x-dev-architect.md`) for details on issue categorization, prioritization, and lifecycle.
124  
125  *   **Bug Reports**: Use the `bug` label.
126  *   **Feature Requests**: Use the `enhancement` label.
127  *   **Documentation Issues**: Use the `documentation` label.
128  *   **CI/CD Issues**: Use the `ci-cd` label.
129  
130  Thank you for contributing to the AI-enhanced CV system!