From 25bee91225432dc8ad6ab9af2d01d774eca829e1 Mon Sep 17 00:00:00 2001 From: Wilmer Arambula Date: Mon, 19 Jan 2026 10:01:06 -0300 Subject: [PATCH 1/3] Add community health files, issue templates, and CI workflows for better project management. --- .github/FUNDING.yml | 2 + .github/ISSUE_TEMPLATE/bug-report.yml | 31 + .github/ISSUE_TEMPLATE/feature-request.yml | 11 + .github/workflows/linter.yml | 17 + .gitignore | 51 ++ ...IZING_GITHUB_ORGANIZATION_CONFIGURATION.md | 632 ++++++++++++++++++ CODE_OF_CONDUCT.md | 102 +++ PULL_REQUEST_TEMPLATE.md | 8 + 8 files changed, 854 insertions(+) create mode 100644 .github/FUNDING.yml create mode 100644 .github/ISSUE_TEMPLATE/bug-report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature-request.yml create mode 100644 .github/workflows/linter.yml create mode 100644 .gitignore create mode 100644 CENTRALIZING_GITHUB_ORGANIZATION_CONFIGURATION.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 PULL_REQUEST_TEMPLATE.md diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..102c3ed --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,2 @@ +--- +github: [terabytesoftw] diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 0000000..3089faf --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,31 @@ +--- +name: 🐛 Bug Report +description: Let us know about problem +body: + - type: markdown + attributes: + value: | + > ⚠️ DON'T CREATE SECURITY ISSUE here. For security vulnerabilities, please use the security advisory feature in the specific project repository instead. + - type: textarea + id: description + attributes: + label: Description + description: Provide a detailed description of the issue. Include all relevant information to help us understand and reproduce the problem. + validations: + required: true + - type: input + id: package-version + attributes: + label: Package version + description: Specify the exact package version you're using + placeholder: "0.1.0" + validations: + required: true + - type: input + id: php-version + attributes: + label: PHP version + description: Specify the exact PHP version you're using (run `php -v` to check) + placeholder: "8.5.0" + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml new file mode 100644 index 0000000..4b9562f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -0,0 +1,11 @@ +--- +name: 🚀 Feature request +description: Suggest an idea for improvement +body: + - type: textarea + attributes: + label: Proposed new feature or change + description: | + Describe the feature and explain why it's needed. + validations: + required: true diff --git a/.github/workflows/linter.yml b/.github/workflows/linter.yml new file mode 100644 index 0000000..7b46557 --- /dev/null +++ b/.github/workflows/linter.yml @@ -0,0 +1,17 @@ +--- +on: + - pull_request + - push + +name: linter + +permissions: + checks: write + contents: read + statuses: write + +jobs: + linter: + uses: yii2-framework/actions/.github/workflows/super-linter.yml@v1 + secrets: + AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d4c5c11 --- /dev/null +++ b/.gitignore @@ -0,0 +1,51 @@ +# codecoverage (if present) +code_coverage + +# codeception (if present) +c3.php + +# composer +composer.lock + +# gitHub copilot config (if present) +.github/agents/** +.github/copilot-instructions.md +.github/copilot/** +.github/instructions/** +.github/prompts/** +.github/skills/** + +# mac ds_store (if present) +.DS_Store + +# netbeans project (if present) +nbproject + +# node_modules (if present) +node_modules +package-lock.json + +# phpstorm project (if present) +.idea + +# phpunit (if present) +.phpunit.cache +.phpunit.result.cache +phpunit.xml* + +# vagrant (if present) +.vagrant + +# vendor +vendor + +# vscode project (if present) +.vscode + +# windows thumbnail cache (if present) +Thumbs.db + +# zend studio for eclipse project (if present) +.buildpath +.project +.settings diff --git a/CENTRALIZING_GITHUB_ORGANIZATION_CONFIGURATION.md b/CENTRALIZING_GITHUB_ORGANIZATION_CONFIGURATION.md new file mode 100644 index 0000000..c541c62 --- /dev/null +++ b/CENTRALIZING_GITHUB_ORGANIZATION_CONFIGURATION.md @@ -0,0 +1,632 @@ +# Centralizing GitHub Organization Configuration: A Comprehensive Guide + +## Introduction + +Managing multiple repositories within a GitHub organization can quickly become challenging without a consistent configuration strategy. Each repository tends to develop its own standards, workflows, and conventions, leading to fragmentation and increased maintenance overhead. + +This article explores how to centralize GitHub organization configuration using the `.github` repository pattern, drawing from real-world practices implemented in the **ui-awesome** organization. We'll cover community health files, reusable workflows, automation tools, and organization-level policies that create a unified development experience across all repositories. + +## The `.github` Repository Pattern + +At the heart of GitHub organization configuration lies a special repository: the `.github` repository. When created as a public repository within your organization, it serves as the default source for community health files that automatically apply to all repositories without their own versions. + +### Why This Matters + +- **Consistency**: All repositories inherit the same standards, policies, and documentation +- **Maintainability**: Updates propagate automatically without touching each repository +- **Onboarding**: New projects start with organization-approved templates immediately +- **Developer Experience**: Contributors encounter familiar patterns across all repositories + +### Repository Structure + +A well-organized `.github` repository typically includes: + +```yaml +.github/ +├── .github/ +│ ├── FUNDING.yml # Sponsorship configuration +│ ├── workflows/ # Reusable workflows +│ │ └── linter.yml +│ └── ISSUE_TEMPLATE/ # Issue and PR templates +│ ├── bug-report.yml +│ └── feature-request.yml +├── CODE_OF_CONDUCT.md # Community standards +├── PULL_REQUEST_TEMPLATE.md # PR guidelines +├── CONTRIBUTING.md # Contribution guide +└── profile/ + └── README.md # Organization profile +``` + +## Community Health Files + +Community health files are the foundation of repository standardization. These files define how contributors interact with your projects and provide essential guidance for participation. + +### Supported Files + +GitHub supports automatic inheritance for these files: + +- **CODE_OF_CONDUCT.md**: Community standards and enforcement procedures +- **CONTRIBUTING.md**: Contribution guidelines and processes +- **FUNDING.yml**: Sponsorship and financial support options +- **GOVERNANCE.md**: Decision-making and governance policies +- **SECURITY.md**: Security reporting procedures +- **SUPPORT.md**: Getting help and support channels +- **Issue templates**: Structured forms in `.github/ISSUE_TEMPLATE/` +- **Pull request templates**: Guidelines in `.github/PULL_REQUEST_TEMPLATE.md` +- **Discussion category forms**: In `.github/discussion_templates/` + +### File Precedence + +GitHub searches for these files in this order: + +1. Repository's `.github/` folder +2. Repository root directory +3. Repository's `docs/` folder +4. Default from organization's `.github` repository + +This hierarchy allows repository-specific overrides while maintaining defaults. + +### Example: Code of Conduct + +```markdown +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone... + +## Our Standards + +Examples of behavior that contributes to a positive environment... + +## Enforcement + +Project maintainers have the right and responsibility to remove, edit, or reject... +``` + +The Contributor Covenant v2.1 is widely adopted and provides clear enforcement guidelines, impact levels, and reporting procedures. + +### Example: Issue Templates + +YAML-based issue templates provide structured forms for reporting bugs and requesting features: + +**bug-report.yml**: + +```yaml +name: Bug report +description: Report a bug to help us improve +title: "[BUG] " +labels: ["bug", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! + + - type: textarea + attributes: + label: Description + description: A clear and concise description of what the bug is + placeholder: Tell us what happened... + validations: + required: true + + - type: textarea + attributes: + label: To Reproduce + description: Steps to reproduce the behavior + placeholder: | + 1. Go to '...' + 2. Click on '...' + 3. Scroll down to '...' + 4. See error + validations: + required: true + + - type: input + attributes: + label: Package Version + description: What version of the package are you using? + placeholder: e.g., 1.2.3 + validations: + required: true + + - type: input + attributes: + label: PHP Version + description: What PHP version are you using? + placeholder: e.g., 8.1.0 + validations: + required: true + + - type: checkboxes + attributes: + label: Security Vulnerability + description: Is this a security vulnerability? + options: + - label: Yes, I'm reporting a security vulnerability + required: false +``` + +Structured templates ensure all necessary information is collected upfront, reducing back-and-forth with reporters and speeding up issue triage. + +## Reusable Workflows + +GitHub Actions workflows can be defined once and reused across multiple repositories. This pattern eliminates duplication and ensures consistent CI/CD practices. + +### Benefits + +- **Centralized Maintenance**: Update workflow logic in one place +- **Consistency**: All repositories run the same checks +- **Reduced Configuration**: Minimal repository-specific setup +- **Version Control**: Pin to specific workflow versions for stability + +### Implementation Pattern + +Create a dedicated repository for workflows (e.g., `org/actions`) and define reusable workflows there: + +**org/actions/.github/workflows/super-linter.yml**: + +YAML example of a linter workflow: + +```yaml +name: Super Linter + +on: + workflow_call: + inputs: + php-version: + description: PHP version to use + required: false + default: '8.1' + type: string + secrets: + AUTH_TOKEN: + required: true + +jobs: + linter: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + php-version: ${{ inputs.php-version }} + coverage: none + + - name: Install dependencies + run: composer install --no-interaction --prefer-dist + + - name: Run linter + run: composer phpcs +``` + +**Individual repository workflow**: + +```yaml +name: Linter + +on: [push, pull_request] + +jobs: + linter: + uses: org/actions/.github/workflows/super-linter.yml@v1 + secrets: + AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + php-version: '8.1' +``` + +### Workflow Versioning + +Use tags or branches to reference workflow versions: + +- `@v1`: Stable version +- `@main`: Latest development version +- `@v1.2.3`: Specific release version + +Semantic versioning allows repositories to control when they adopt workflow changes. + +## Automated Dependency Management + +Keeping dependencies up-to-date is critical for security and compatibility. Dependabot automates this process across your organization. + +### Configuration + +**dependabot.yml**: + +```yaml +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "daily" + labels: + - "dependencies" + - "github-actions" + + - package-ecosystem: "composer" + directory: "/" + schedule: + interval: "daily" + versioning-strategy: increase-if-necessary + labels: + - "dependencies" + - "php" + commit-message: + prefix: "Composer" + include: "scope" +``` + +### Best Practices + +- **Daily checks**: Catch security vulnerabilities early +- **Separate schedules**: Different intervals for different ecosystems +- **Appropriate versioning strategies**: + - `increase-if-necessary`: For libraries (only update when needed) + - `auto-increase`: For applications (always use latest) + - `lockfile-only`: Only update lockfile +- **Automated merges**: Combine with branch protection rules for low-risk updates + +## Comprehensive Testing Strategy + +A mature organization configuration implements multiple layers of automated testing: + +### 1. Code Linting + +```yaml +name: Linter + +on: [push, pull_request] + +jobs: + phpcs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: shivammathur/setup-php@v2 + with: + php-version: '8.1' + - run: composer install + - run: composer phpcs +``` + +Enforces PSR-12 coding standards and project-specific style rules. + +### 2. Static Analysis + +```yaml +name: Static Analysis + +on: [push, pull_request] + +jobs: + psalm: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: shivammathur/setup-php@v2 + with: + php-version: '8.1' + - run: composer install + - run: vendor/bin/psalm --show-info=false +``` + +Detects bugs, type errors, and potential issues without executing code. + +### 3. Dependency Checks + +```yaml +name: Dependency Check + +on: [push, pull_request] + +jobs: + security: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: shivammathur/setup-php@v2 + with: + php-version: '8.1' + - run: composer install + - run: vendor/bin/enlightn --check=security +``` + +Scans dependencies for known security vulnerabilities. + +### 4. Build Testing + +```yaml +name: Build + +on: [push, pull_request] + +jobs: + test: + runs-on: ubuntu-latest + strategy: + matrix: + php-version: ['8.1'] + dependencies: ['highest', 'lowest'] + steps: + - uses: actions/checkout@v4 + - uses: shivammathur/setup-php@v2 + with: + php-version: ${{ matrix.php-version }} + coverage: xdebug + - run: composer update --prefer-dist --no-interaction + if: matrix.dependencies == 'highest' + - run: composer update --prefer-dist --no-interaction --prefer-lowest + if: matrix.dependencies == 'lowest' + - run: composer test + - uses: codecov/codecov-action@v3 + with: + files: ./coverage.xml +``` + +Runs the full test suite with PHPUnit across multiple PHP versions and dependency configurations. + +### 5. Mutation Testing + +```yaml +name: Mutation Testing + +on: [push, pull_request] + +jobs: + infection: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: shivammathur/setup-php@v2 + with: + php-version: '8.1' + - run: composer install + - run: composer infection --show-mutations +``` + +Validates test quality by introducing mutations and checking if tests catch them. + +## Organization-Level Policies + +Beyond repository-specific configuration, GitHub provides organization-wide policy enforcement mechanisms. + +### Rulesets + +Rulesets enforce policies across multiple repositories: + +- **Branch protection rules**: Require reviews, status checks, and signed commits +- **Push restrictions**: Control who can push to branches +- **Tag management**: Prevent accidental tag deletions or modifications +- **Repository renaming**: Prevent repository name changes + +Example ruleset configuration: + +```json +{ + "name": "Production Branch Protection", + "target": "branch", + "enforcement": "active", + "conditions": { + "ref_name": { + "include": ["refs/heads/main", "refs/heads/master"], + "exclude": [] + } + }, + "rules": [ + { + "type": "pull_request", + "parameters": { + "dismiss_stale_reviews_on_push": true, + "require_code_owner_review": true, + "required_approving_review_count": 1 + } + }, + { + "type": "required_status_checks", + "parameters": { + "strict": true, + "contexts": ["linter", "build", "static-analysis"] + } + } + ] +} +``` + +### Team Management + +Use teams for access management rather than individual permissions: + +- **Base teams**: Provide core permissions (read, triage, write) +- **Permission inheritance**: Child teams inherit parent permissions +- **Multiple owners**: Ensure continuity for critical projects +- **Custom roles**: Fine-grained control with administrator, maintainer, and member roles + +### GitHub Apps and Integrations + +Manage organization-wide applications: + +- **Review installed apps**: Audit permissions and access +- **Minimum required permissions**: Follow the principle of least privilege +- **Repository-specific access**: Restrict app access to necessary repositories +- **Regular reviews**: Periodically audit and remove unused apps + +## Implementation Guide + +### Phase 1: Foundation + +1. **Create the `.github` repository** + ```bash + # Create as a public repository + gh repo create .github --public --description "Organization-wide configuration" + ``` + +2. **Add core community health files** + - Create `CODE_OF_CONDUCT.md` using the Contributor Covenant + - Add `CONTRIBUTING.md` with your contribution guidelines + - Configure `FUNDING.yml` for sponsorship + +3. **Create templates** + - Develop issue templates for common scenarios + - Create pull request templates with checklists + - Add discussion category forms if needed + +### Phase 2: Workflow Infrastructure + +1. **Create reusable workflow repository** + ```bash + gh repo create actions --public --description "Shared GitHub Actions workflows" + ``` + +2. **Develop core workflows** + - Linting workflow + - Testing workflow + - Security scanning workflow + - Deployment workflow + +3. **Implement versioning** + ```bash + git tag v1.0.0 + git push origin v1.0.0 + ``` + +### Phase 3: Repository Initialization + +1. **Create repository templates** + ```bash + gh repo create my-package --template org/template-repo + ``` + +2. **Configure Dependabot** + - Add `dependabot.yml` to new repositories + - Set appropriate schedules and versioning strategies + +3. **Add repository-specific workflows** + - Reference reusable workflows from `org/actions` + - Override with local configurations if needed + +### Phase 4: Organization Policies + +1. **Set up rulesets** + ```bash + gh api orgs/org/rulesets --input ruleset.json + ``` + +2. **Configure team structure** + - Create teams for different access levels + - Assign repositories to teams + - Set appropriate permissions + +3. **Review and configure GitHub Apps** + - Audit existing apps + - Configure new integrations + - Document approved apps + +### Phase 5: Documentation and Training + +1. **Create organization documentation** + - README in `.github` repository + - Contribution guidelines + - Troubleshooting guides + +2. **Develop onboarding materials** + - Quick start guides + - Video tutorials + - FAQ documents + +3. **Establish maintenance procedures** + - Update schedules for dependencies + - Review cycles for workflows + - Incident response procedures + +## Best Practices + +### 1. Start Simple + +Begin with essential files and gradually add complexity: +- Core community health files first +- Basic workflows +- Advanced features later + +### 2. Version Control Everything + +- Tag workflow releases +- Document breaking changes +- Maintain backwards compatibility when possible + +### 3. Provide Overrides + +Allow repository-specific customization: +- Repository files override organization defaults +- Accept PRs with local variations +- Balance consistency with flexibility + +### 4. Monitor and Iterate + +- Review workflow performance +- Gather feedback from contributors +- Update based on lessons learned + +### 5. Security First + +- Use secrets management for sensitive data +- Review dependencies regularly +- Implement security scanning +- Follow the principle of least privilege + +## Common Pitfalls + +### 1. Private `.github` Repository + +The `.github` repository must be public for templates to apply organization-wide. Private repositories are not supported for this feature. + +### 2. Over-Engineering + +Avoid creating complex workflows that are difficult to maintain. Start simple and add complexity only when needed. + +### 3. Ignoring Repository Context + +Not all repositories need the same configuration. Allow for flexibility and acknowledge different project requirements. + +### 4. Forgetting Documentation + +Without clear documentation, contributors may not understand the purpose or usage of configuration files. + +### 5. Inconsistent Updates + +Update shared configurations regularly but communicate changes clearly to maintain stability across repositories. + +## Conclusion + +Centralizing GitHub organization configuration through the `.github` repository pattern provides significant benefits for consistency, maintainability, and developer experience. By leveraging GitHub's built-in features for community health files, reusable workflows, automated dependency management, and organization-level policies, you can create a unified development environment that scales as your organization grows. + +The key is to start with essential configurations, iterate based on experience, and maintain flexibility for repository-specific needs. With proper planning and ongoing maintenance, this approach reduces administrative overhead while improving code quality and contributor satisfaction. + +## Resources + +### Official GitHub Documentation + +- [Default Community Health Files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file) +- [Reusable Workflows](https://docs.github.com/en/actions/sharing-automations/reusing-workflows) +- [Dependabot Configuration](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file) +- [Organization Rulesets](https://docs.github.com/en/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization) +- [Team Management](https://docs.github.com/en/organizations/organizing-members-into-teams/about-teams) +- [Best Practices for Organizations](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/best-practices-for-organizations) + +### Example Repositories + +- [ui-awesome/.github](https://github.com/ui-awesome/.github): Complete implementation example +- [GitHub's .github repository](https://github.com/github/.github): Reference implementation + +### Tools and Integrations + +- [GitHub Actions](https://github.com/features/actions): Custom automation +- [Dependabot](https://docs.github.com/en/code-security/dependabot): Automated dependency updates +- [CodeQL](https://codeql.github.com/): Security scanning +- [Codecov](https://codecov.io/): Coverage reporting diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..6ed6edb --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,102 @@ +# Code of Conduct + +## Our Pledge + +As contributors and maintainers of this project, and in order to keep community open and welcoming, we ask to +respect all community members. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Core team members are responsible for clarifying and enforcing our standards of acceptable behavior and will take +appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Core team members have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, +issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for +moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing +the community in public spaces. Examples of representing a project or community include using an official email +address, posting via an official social media account, within project GitHub, official forum or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting core team members. All +complaints will be reviewed and investigated promptly and fairly. + +All core team members are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement Guidelines + +Core team members will follow these Community Impact Guidelines in determining the consequences for any action they +deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in +the community. + +**Consequence**: A private, written warning from core team members, providing clarity around the nature of the violation +and an explanation of why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of actions. + +**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including +unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding +interactions in community spaces as well as external channels like social media. Violating these terms may lead to +a temporary or permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified +period of time. No public or private interaction with the people involved, including unsolicited interaction with those +enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate +behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..caa140a --- /dev/null +++ b/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,8 @@ +# Pull Request + +| Q | A | +| ------------ | ------------------------------------------------------------------ | +| Is bugfix? | ✔️/❌ | +| New feature? | ✔️/❌ | +| Breaks BC? | ✔️/❌ | +| Fixed issues | | From f6372b625823f04b8f3719688da2240825751b8b Mon Sep 17 00:00:00 2001 From: Wilmer Arambula Date: Mon, 19 Jan 2026 10:05:45 -0300 Subject: [PATCH 2/3] Remove unsed file. --- ...IZING_GITHUB_ORGANIZATION_CONFIGURATION.md | 632 ------------------ 1 file changed, 632 deletions(-) delete mode 100644 CENTRALIZING_GITHUB_ORGANIZATION_CONFIGURATION.md diff --git a/CENTRALIZING_GITHUB_ORGANIZATION_CONFIGURATION.md b/CENTRALIZING_GITHUB_ORGANIZATION_CONFIGURATION.md deleted file mode 100644 index c541c62..0000000 --- a/CENTRALIZING_GITHUB_ORGANIZATION_CONFIGURATION.md +++ /dev/null @@ -1,632 +0,0 @@ -# Centralizing GitHub Organization Configuration: A Comprehensive Guide - -## Introduction - -Managing multiple repositories within a GitHub organization can quickly become challenging without a consistent configuration strategy. Each repository tends to develop its own standards, workflows, and conventions, leading to fragmentation and increased maintenance overhead. - -This article explores how to centralize GitHub organization configuration using the `.github` repository pattern, drawing from real-world practices implemented in the **ui-awesome** organization. We'll cover community health files, reusable workflows, automation tools, and organization-level policies that create a unified development experience across all repositories. - -## The `.github` Repository Pattern - -At the heart of GitHub organization configuration lies a special repository: the `.github` repository. When created as a public repository within your organization, it serves as the default source for community health files that automatically apply to all repositories without their own versions. - -### Why This Matters - -- **Consistency**: All repositories inherit the same standards, policies, and documentation -- **Maintainability**: Updates propagate automatically without touching each repository -- **Onboarding**: New projects start with organization-approved templates immediately -- **Developer Experience**: Contributors encounter familiar patterns across all repositories - -### Repository Structure - -A well-organized `.github` repository typically includes: - -```yaml -.github/ -├── .github/ -│ ├── FUNDING.yml # Sponsorship configuration -│ ├── workflows/ # Reusable workflows -│ │ └── linter.yml -│ └── ISSUE_TEMPLATE/ # Issue and PR templates -│ ├── bug-report.yml -│ └── feature-request.yml -├── CODE_OF_CONDUCT.md # Community standards -├── PULL_REQUEST_TEMPLATE.md # PR guidelines -├── CONTRIBUTING.md # Contribution guide -└── profile/ - └── README.md # Organization profile -``` - -## Community Health Files - -Community health files are the foundation of repository standardization. These files define how contributors interact with your projects and provide essential guidance for participation. - -### Supported Files - -GitHub supports automatic inheritance for these files: - -- **CODE_OF_CONDUCT.md**: Community standards and enforcement procedures -- **CONTRIBUTING.md**: Contribution guidelines and processes -- **FUNDING.yml**: Sponsorship and financial support options -- **GOVERNANCE.md**: Decision-making and governance policies -- **SECURITY.md**: Security reporting procedures -- **SUPPORT.md**: Getting help and support channels -- **Issue templates**: Structured forms in `.github/ISSUE_TEMPLATE/` -- **Pull request templates**: Guidelines in `.github/PULL_REQUEST_TEMPLATE.md` -- **Discussion category forms**: In `.github/discussion_templates/` - -### File Precedence - -GitHub searches for these files in this order: - -1. Repository's `.github/` folder -2. Repository root directory -3. Repository's `docs/` folder -4. Default from organization's `.github` repository - -This hierarchy allows repository-specific overrides while maintaining defaults. - -### Example: Code of Conduct - -```markdown -# Contributor Covenant Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone... - -## Our Standards - -Examples of behavior that contributes to a positive environment... - -## Enforcement - -Project maintainers have the right and responsibility to remove, edit, or reject... -``` - -The Contributor Covenant v2.1 is widely adopted and provides clear enforcement guidelines, impact levels, and reporting procedures. - -### Example: Issue Templates - -YAML-based issue templates provide structured forms for reporting bugs and requesting features: - -**bug-report.yml**: - -```yaml -name: Bug report -description: Report a bug to help us improve -title: "[BUG] " -labels: ["bug", "triage"] -body: - - type: markdown - attributes: - value: | - Thanks for taking the time to fill out this bug report! - - - type: textarea - attributes: - label: Description - description: A clear and concise description of what the bug is - placeholder: Tell us what happened... - validations: - required: true - - - type: textarea - attributes: - label: To Reproduce - description: Steps to reproduce the behavior - placeholder: | - 1. Go to '...' - 2. Click on '...' - 3. Scroll down to '...' - 4. See error - validations: - required: true - - - type: input - attributes: - label: Package Version - description: What version of the package are you using? - placeholder: e.g., 1.2.3 - validations: - required: true - - - type: input - attributes: - label: PHP Version - description: What PHP version are you using? - placeholder: e.g., 8.1.0 - validations: - required: true - - - type: checkboxes - attributes: - label: Security Vulnerability - description: Is this a security vulnerability? - options: - - label: Yes, I'm reporting a security vulnerability - required: false -``` - -Structured templates ensure all necessary information is collected upfront, reducing back-and-forth with reporters and speeding up issue triage. - -## Reusable Workflows - -GitHub Actions workflows can be defined once and reused across multiple repositories. This pattern eliminates duplication and ensures consistent CI/CD practices. - -### Benefits - -- **Centralized Maintenance**: Update workflow logic in one place -- **Consistency**: All repositories run the same checks -- **Reduced Configuration**: Minimal repository-specific setup -- **Version Control**: Pin to specific workflow versions for stability - -### Implementation Pattern - -Create a dedicated repository for workflows (e.g., `org/actions`) and define reusable workflows there: - -**org/actions/.github/workflows/super-linter.yml**: - -YAML example of a linter workflow: - -```yaml -name: Super Linter - -on: - workflow_call: - inputs: - php-version: - description: PHP version to use - required: false - default: '8.1' - type: string - secrets: - AUTH_TOKEN: - required: true - -jobs: - linter: - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v4 - - - name: Setup PHP - uses: shivammathur/setup-php@v2 - with: - php-version: ${{ inputs.php-version }} - coverage: none - - - name: Install dependencies - run: composer install --no-interaction --prefer-dist - - - name: Run linter - run: composer phpcs -``` - -**Individual repository workflow**: - -```yaml -name: Linter - -on: [push, pull_request] - -jobs: - linter: - uses: org/actions/.github/workflows/super-linter.yml@v1 - secrets: - AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - php-version: '8.1' -``` - -### Workflow Versioning - -Use tags or branches to reference workflow versions: - -- `@v1`: Stable version -- `@main`: Latest development version -- `@v1.2.3`: Specific release version - -Semantic versioning allows repositories to control when they adopt workflow changes. - -## Automated Dependency Management - -Keeping dependencies up-to-date is critical for security and compatibility. Dependabot automates this process across your organization. - -### Configuration - -**dependabot.yml**: - -```yaml -version: 2 -updates: - - package-ecosystem: "github-actions" - directory: "/" - schedule: - interval: "daily" - labels: - - "dependencies" - - "github-actions" - - - package-ecosystem: "composer" - directory: "/" - schedule: - interval: "daily" - versioning-strategy: increase-if-necessary - labels: - - "dependencies" - - "php" - commit-message: - prefix: "Composer" - include: "scope" -``` - -### Best Practices - -- **Daily checks**: Catch security vulnerabilities early -- **Separate schedules**: Different intervals for different ecosystems -- **Appropriate versioning strategies**: - - `increase-if-necessary`: For libraries (only update when needed) - - `auto-increase`: For applications (always use latest) - - `lockfile-only`: Only update lockfile -- **Automated merges**: Combine with branch protection rules for low-risk updates - -## Comprehensive Testing Strategy - -A mature organization configuration implements multiple layers of automated testing: - -### 1. Code Linting - -```yaml -name: Linter - -on: [push, pull_request] - -jobs: - phpcs: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: shivammathur/setup-php@v2 - with: - php-version: '8.1' - - run: composer install - - run: composer phpcs -``` - -Enforces PSR-12 coding standards and project-specific style rules. - -### 2. Static Analysis - -```yaml -name: Static Analysis - -on: [push, pull_request] - -jobs: - psalm: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: shivammathur/setup-php@v2 - with: - php-version: '8.1' - - run: composer install - - run: vendor/bin/psalm --show-info=false -``` - -Detects bugs, type errors, and potential issues without executing code. - -### 3. Dependency Checks - -```yaml -name: Dependency Check - -on: [push, pull_request] - -jobs: - security: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: shivammathur/setup-php@v2 - with: - php-version: '8.1' - - run: composer install - - run: vendor/bin/enlightn --check=security -``` - -Scans dependencies for known security vulnerabilities. - -### 4. Build Testing - -```yaml -name: Build - -on: [push, pull_request] - -jobs: - test: - runs-on: ubuntu-latest - strategy: - matrix: - php-version: ['8.1'] - dependencies: ['highest', 'lowest'] - steps: - - uses: actions/checkout@v4 - - uses: shivammathur/setup-php@v2 - with: - php-version: ${{ matrix.php-version }} - coverage: xdebug - - run: composer update --prefer-dist --no-interaction - if: matrix.dependencies == 'highest' - - run: composer update --prefer-dist --no-interaction --prefer-lowest - if: matrix.dependencies == 'lowest' - - run: composer test - - uses: codecov/codecov-action@v3 - with: - files: ./coverage.xml -``` - -Runs the full test suite with PHPUnit across multiple PHP versions and dependency configurations. - -### 5. Mutation Testing - -```yaml -name: Mutation Testing - -on: [push, pull_request] - -jobs: - infection: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: shivammathur/setup-php@v2 - with: - php-version: '8.1' - - run: composer install - - run: composer infection --show-mutations -``` - -Validates test quality by introducing mutations and checking if tests catch them. - -## Organization-Level Policies - -Beyond repository-specific configuration, GitHub provides organization-wide policy enforcement mechanisms. - -### Rulesets - -Rulesets enforce policies across multiple repositories: - -- **Branch protection rules**: Require reviews, status checks, and signed commits -- **Push restrictions**: Control who can push to branches -- **Tag management**: Prevent accidental tag deletions or modifications -- **Repository renaming**: Prevent repository name changes - -Example ruleset configuration: - -```json -{ - "name": "Production Branch Protection", - "target": "branch", - "enforcement": "active", - "conditions": { - "ref_name": { - "include": ["refs/heads/main", "refs/heads/master"], - "exclude": [] - } - }, - "rules": [ - { - "type": "pull_request", - "parameters": { - "dismiss_stale_reviews_on_push": true, - "require_code_owner_review": true, - "required_approving_review_count": 1 - } - }, - { - "type": "required_status_checks", - "parameters": { - "strict": true, - "contexts": ["linter", "build", "static-analysis"] - } - } - ] -} -``` - -### Team Management - -Use teams for access management rather than individual permissions: - -- **Base teams**: Provide core permissions (read, triage, write) -- **Permission inheritance**: Child teams inherit parent permissions -- **Multiple owners**: Ensure continuity for critical projects -- **Custom roles**: Fine-grained control with administrator, maintainer, and member roles - -### GitHub Apps and Integrations - -Manage organization-wide applications: - -- **Review installed apps**: Audit permissions and access -- **Minimum required permissions**: Follow the principle of least privilege -- **Repository-specific access**: Restrict app access to necessary repositories -- **Regular reviews**: Periodically audit and remove unused apps - -## Implementation Guide - -### Phase 1: Foundation - -1. **Create the `.github` repository** - ```bash - # Create as a public repository - gh repo create .github --public --description "Organization-wide configuration" - ``` - -2. **Add core community health files** - - Create `CODE_OF_CONDUCT.md` using the Contributor Covenant - - Add `CONTRIBUTING.md` with your contribution guidelines - - Configure `FUNDING.yml` for sponsorship - -3. **Create templates** - - Develop issue templates for common scenarios - - Create pull request templates with checklists - - Add discussion category forms if needed - -### Phase 2: Workflow Infrastructure - -1. **Create reusable workflow repository** - ```bash - gh repo create actions --public --description "Shared GitHub Actions workflows" - ``` - -2. **Develop core workflows** - - Linting workflow - - Testing workflow - - Security scanning workflow - - Deployment workflow - -3. **Implement versioning** - ```bash - git tag v1.0.0 - git push origin v1.0.0 - ``` - -### Phase 3: Repository Initialization - -1. **Create repository templates** - ```bash - gh repo create my-package --template org/template-repo - ``` - -2. **Configure Dependabot** - - Add `dependabot.yml` to new repositories - - Set appropriate schedules and versioning strategies - -3. **Add repository-specific workflows** - - Reference reusable workflows from `org/actions` - - Override with local configurations if needed - -### Phase 4: Organization Policies - -1. **Set up rulesets** - ```bash - gh api orgs/org/rulesets --input ruleset.json - ``` - -2. **Configure team structure** - - Create teams for different access levels - - Assign repositories to teams - - Set appropriate permissions - -3. **Review and configure GitHub Apps** - - Audit existing apps - - Configure new integrations - - Document approved apps - -### Phase 5: Documentation and Training - -1. **Create organization documentation** - - README in `.github` repository - - Contribution guidelines - - Troubleshooting guides - -2. **Develop onboarding materials** - - Quick start guides - - Video tutorials - - FAQ documents - -3. **Establish maintenance procedures** - - Update schedules for dependencies - - Review cycles for workflows - - Incident response procedures - -## Best Practices - -### 1. Start Simple - -Begin with essential files and gradually add complexity: -- Core community health files first -- Basic workflows -- Advanced features later - -### 2. Version Control Everything - -- Tag workflow releases -- Document breaking changes -- Maintain backwards compatibility when possible - -### 3. Provide Overrides - -Allow repository-specific customization: -- Repository files override organization defaults -- Accept PRs with local variations -- Balance consistency with flexibility - -### 4. Monitor and Iterate - -- Review workflow performance -- Gather feedback from contributors -- Update based on lessons learned - -### 5. Security First - -- Use secrets management for sensitive data -- Review dependencies regularly -- Implement security scanning -- Follow the principle of least privilege - -## Common Pitfalls - -### 1. Private `.github` Repository - -The `.github` repository must be public for templates to apply organization-wide. Private repositories are not supported for this feature. - -### 2. Over-Engineering - -Avoid creating complex workflows that are difficult to maintain. Start simple and add complexity only when needed. - -### 3. Ignoring Repository Context - -Not all repositories need the same configuration. Allow for flexibility and acknowledge different project requirements. - -### 4. Forgetting Documentation - -Without clear documentation, contributors may not understand the purpose or usage of configuration files. - -### 5. Inconsistent Updates - -Update shared configurations regularly but communicate changes clearly to maintain stability across repositories. - -## Conclusion - -Centralizing GitHub organization configuration through the `.github` repository pattern provides significant benefits for consistency, maintainability, and developer experience. By leveraging GitHub's built-in features for community health files, reusable workflows, automated dependency management, and organization-level policies, you can create a unified development environment that scales as your organization grows. - -The key is to start with essential configurations, iterate based on experience, and maintain flexibility for repository-specific needs. With proper planning and ongoing maintenance, this approach reduces administrative overhead while improving code quality and contributor satisfaction. - -## Resources - -### Official GitHub Documentation - -- [Default Community Health Files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file) -- [Reusable Workflows](https://docs.github.com/en/actions/sharing-automations/reusing-workflows) -- [Dependabot Configuration](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file) -- [Organization Rulesets](https://docs.github.com/en/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization) -- [Team Management](https://docs.github.com/en/organizations/organizing-members-into-teams/about-teams) -- [Best Practices for Organizations](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/best-practices-for-organizations) - -### Example Repositories - -- [ui-awesome/.github](https://github.com/ui-awesome/.github): Complete implementation example -- [GitHub's .github repository](https://github.com/github/.github): Reference implementation - -### Tools and Integrations - -- [GitHub Actions](https://github.com/features/actions): Custom automation -- [Dependabot](https://docs.github.com/en/code-security/dependabot): Automated dependency updates -- [CodeQL](https://codeql.github.com/): Security scanning -- [Codecov](https://codecov.io/): Coverage reporting From 9b9fa8b4ef378262c3db888246e361849289578a Mon Sep 17 00:00:00 2001 From: Wilmer Arambula Date: Mon, 19 Jan 2026 10:10:00 -0300 Subject: [PATCH 3/3] Fix formatting inconsistencies in `README.md`. --- profile/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/profile/README.md b/profile/README.md index 9d29c72..22496a6 100644 --- a/profile/README.md +++ b/profile/README.md @@ -1,25 +1,25 @@ # PHP Forge: Code Craftsmanship for Reliability -**PHP Forge** houses the foundational, framework-agnostic tools that power the next generation of PHP applications. +**PHP Forge** houses the foundational, framework-agnostic tools that power the next generation of PHP applications. ## 🔨 Our Philosophy -* **Zero Dependencies:** Libraries that stand on their own. -* **Battle Tested:** 100% Code Coverage. -* **Strict Standards:** Strongly typed PHP and strict mode enabled. +- **Zero Dependencies:** Libraries that stand on their own. +- **Battle Tested:** 100% Code Coverage. +- **Strict Standards:** Strongly typed PHP and strict mode enabled. ## 🛠️ The Toolset -* **[Foxy](https://github.com/php-forge/foxy):** Fast, reliable, and secure BUN/NPM/Yarn/PNpM bridge for Composer. +- **[Foxy](https://github.com/php-forge/foxy):** Fast, reliable, and secure BUN/NPM/Yarn/PNpM bridge for Composer. ## 🌐 Part of the Ecosystem Maintained by the core team of [yii2-framework](https://github.com/yii2-framework) and [yii2-extensions](https://github.com/yii2-extensions). ------ +---
- + Sponsor php-forge on GitHub -
\ No newline at end of file +