|
| 1 | +# Copyright The Linux Foundation and each contributor to LFX. |
| 2 | + |
| 3 | +# SPDX-License-Identifier: MIT |
| 4 | + |
| 5 | +# Contributing to LFX PCC |
| 6 | + |
| 7 | +Thank you for your interest in contributing to LFX PCC! This document provides guidelines and instructions for contributing to the project. |
| 8 | + |
| 9 | +## Table of Contents |
| 10 | + |
| 11 | +- [Code of Conduct](#code-of-conduct) |
| 12 | +- [Getting Started](#getting-started) |
| 13 | +- [Development Setup](#development-setup) |
| 14 | +- [License Headers](#license-headers) |
| 15 | +- [Code Style](#code-style) |
| 16 | +- [Commit Messages](#commit-messages) |
| 17 | +- [Pull Request Process](#pull-request-process) |
| 18 | +- [Testing](#testing) |
| 19 | + |
| 20 | +## Code of Conduct |
| 21 | + |
| 22 | +By participating in this project, you agree to abide by the [Linux Foundation Code of Conduct](https://www.linuxfoundation.org/code-of-conduct/). |
| 23 | + |
| 24 | +## Getting Started |
| 25 | + |
| 26 | +1. Fork the repository |
| 27 | +2. Clone your fork locally |
| 28 | +3. Create a new branch for your feature or bug fix |
| 29 | +4. Make your changes |
| 30 | +5. Push your changes to your fork |
| 31 | +6. Submit a pull request |
| 32 | + |
| 33 | +## Development Setup |
| 34 | + |
| 35 | +Please refer to the [README.md](README.md) for detailed setup instructions. |
| 36 | + |
| 37 | +## License Headers |
| 38 | + |
| 39 | +**IMPORTANT**: All source code files must include the appropriate license header. This is enforced by our CI/CD pipeline. |
| 40 | + |
| 41 | +### Required Format |
| 42 | + |
| 43 | +The license header must appear in the first 4 lines of every source file and must contain the exact text: |
| 44 | + |
| 45 | +``` |
| 46 | +Copyright The Linux Foundation and each contributor to LFX. |
| 47 | +SPDX-License-Identifier: MIT |
| 48 | +``` |
| 49 | + |
| 50 | +### File Type Examples |
| 51 | + |
| 52 | +#### TypeScript/JavaScript Files (.ts, .js) |
| 53 | + |
| 54 | +```typescript |
| 55 | +// Copyright The Linux Foundation and each contributor to LFX. |
| 56 | +// SPDX-License-Identifier: MIT |
| 57 | + |
| 58 | +// Your code here... |
| 59 | +``` |
| 60 | + |
| 61 | +#### HTML Files (.html) |
| 62 | + |
| 63 | +```html |
| 64 | +<!-- Copyright The Linux Foundation and each contributor to LFX. --> |
| 65 | +<!-- SPDX-License-Identifier: MIT --> |
| 66 | + |
| 67 | +<!-- Your HTML here... --> |
| 68 | +``` |
| 69 | + |
| 70 | +#### CSS/SCSS Files (.css, .scss) |
| 71 | + |
| 72 | +```css |
| 73 | +/* Copyright The Linux Foundation and each contributor to LFX. */ |
| 74 | +/* SPDX-License-Identifier: MIT */ |
| 75 | + |
| 76 | +/* Your styles here... */ |
| 77 | +``` |
| 78 | + |
| 79 | +#### YAML Files (.yml, .yaml) |
| 80 | + |
| 81 | +```yaml |
| 82 | +# Copyright The Linux Foundation and each contributor to LFX. |
| 83 | +# SPDX-License-Identifier: MIT |
| 84 | + |
| 85 | +# Your YAML content here... |
| 86 | +``` |
| 87 | + |
| 88 | +#### Shell Scripts (.sh) |
| 89 | + |
| 90 | +```bash |
| 91 | +#!/usr/bin/env bash |
| 92 | + |
| 93 | +# Copyright The Linux Foundation and each contributor to LFX. |
| 94 | +# SPDX-License-Identifier: MIT |
| 95 | + |
| 96 | +# Your script here... |
| 97 | +``` |
| 98 | + |
| 99 | +### Checking License Headers |
| 100 | + |
| 101 | +Before committing, run the license header check: |
| 102 | + |
| 103 | +```bash |
| 104 | +./check-headers.sh |
| 105 | +``` |
| 106 | + |
| 107 | +This script will identify any files missing the required license header. The script automatically excludes: |
| 108 | + |
| 109 | +- `node_modules/` |
| 110 | +- `.angular/` |
| 111 | +- `dist/` |
| 112 | +- Other generated/cached files |
| 113 | + |
| 114 | +### Automated Checks |
| 115 | + |
| 116 | +- **Pre-commit Hook**: The license header check runs automatically before each commit |
| 117 | +- **CI Pipeline**: GitHub Actions will verify all files have proper headers on every pull request |
| 118 | + |
| 119 | +## Code Style |
| 120 | + |
| 121 | +### General Guidelines |
| 122 | + |
| 123 | +- Follow the existing code style in the project |
| 124 | +- Use TypeScript for all new code |
| 125 | +- Follow Angular style guide for Angular components |
| 126 | +- Use meaningful variable and function names |
| 127 | +- Add comments for complex logic |
| 128 | + |
| 129 | +### Linting |
| 130 | + |
| 131 | +The project uses ESLint and Prettier for code formatting. Run linting before committing: |
| 132 | + |
| 133 | +```bash |
| 134 | +# Run linting for all packages |
| 135 | +yarn lint |
| 136 | + |
| 137 | +# Run linting with auto-fix |
| 138 | +yarn lint:fix |
| 139 | + |
| 140 | +# Run formatting |
| 141 | +yarn format |
| 142 | +``` |
| 143 | + |
| 144 | +## Commit Messages |
| 145 | + |
| 146 | +### Format |
| 147 | + |
| 148 | +Follow the conventional commit format: |
| 149 | + |
| 150 | +``` |
| 151 | +type(scope): subject |
| 152 | +
|
| 153 | +body |
| 154 | +
|
| 155 | +footer |
| 156 | +``` |
| 157 | + |
| 158 | +### Types |
| 159 | + |
| 160 | +- `feat`: New feature |
| 161 | +- `fix`: Bug fix |
| 162 | +- `docs`: Documentation changes |
| 163 | +- `style`: Code style changes (formatting, etc.) |
| 164 | +- `refactor`: Code refactoring |
| 165 | +- `test`: Adding or updating tests |
| 166 | +- `chore`: Maintenance tasks |
| 167 | + |
| 168 | +### Examples |
| 169 | + |
| 170 | +``` |
| 171 | +feat(auth): add Auth0 integration |
| 172 | +
|
| 173 | +Implemented Auth0 authentication using express-openid-connect |
| 174 | +middleware with proper token refresh handling. |
| 175 | +
|
| 176 | +Closes #123 |
| 177 | +``` |
| 178 | + |
| 179 | +### Sign-off |
| 180 | + |
| 181 | +All commits must be signed off: |
| 182 | + |
| 183 | +```bash |
| 184 | +git commit --signoff |
| 185 | +``` |
| 186 | + |
| 187 | +This adds a `Signed-off-by` line to your commit message. |
| 188 | + |
| 189 | +## Pull Request Process |
| 190 | + |
| 191 | +1. **Update Documentation**: Update relevant documentation for any new features |
| 192 | +2. **Add Tests**: Include tests for new functionality |
| 193 | +3. **Pass All Checks**: Ensure all tests and linting pass |
| 194 | +4. **License Headers**: Verify all new files have proper license headers |
| 195 | +5. **Clear Description**: Provide a clear description of changes in the PR |
| 196 | +6. **Link Issues**: Reference any related issues |
| 197 | + |
| 198 | +### PR Title Format |
| 199 | + |
| 200 | +Use the same conventional commit format for PR titles: |
| 201 | + |
| 202 | +``` |
| 203 | +feat(component): add new table component |
| 204 | +``` |
| 205 | + |
| 206 | +## Testing |
| 207 | + |
| 208 | +### Running Tests |
| 209 | + |
| 210 | +```bash |
| 211 | +# Run all tests |
| 212 | +yarn test |
| 213 | + |
| 214 | +# Run tests in watch mode |
| 215 | +yarn test:watch |
| 216 | + |
| 217 | +# Run e2e tests |
| 218 | +yarn e2e |
| 219 | +``` |
| 220 | + |
| 221 | +### Test Requirements |
| 222 | + |
| 223 | +- All new features must include unit tests |
| 224 | +- Maintain or improve code coverage |
| 225 | +- E2E tests for critical user flows |
| 226 | + |
| 227 | +## Questions? |
| 228 | + |
| 229 | +If you have questions about contributing, please: |
| 230 | + |
| 231 | +1. Check existing issues and discussions |
| 232 | +2. Open a new issue for clarification |
| 233 | +3. Join our community channels |
| 234 | + |
| 235 | +Thank you for contributing to LFX PCC! |
0 commit comments