diff --git a/.github/BRANCH_PROTECTION.md b/.github/BRANCH_PROTECTION.md new file mode 100644 index 0000000..41588c0 --- /dev/null +++ b/.github/BRANCH_PROTECTION.md @@ -0,0 +1,112 @@ +# Branch Protection Configuration + +This document describes how to configure branch protection rules for the `main`/`master` branch to ensure all CI checks pass before merging pull requests. + +## Required Status Checks + +The repository has a CI workflow (`.github/workflows/main.yml`) that runs comprehensive tests across multiple configurations: +- **Compilers**: `lualatex`, `pdflatex` +- **Faculties**: `eiti`, `meil` +- **Languages**: `eng`, `pol` +- **Thesis Types**: `EngineerThesis`, `MasterThesis` + +This creates 16 test matrix jobs (2×2×2×2) that must all pass before a pull request can be merged. + +## Setting Up Branch Protection + +### Via GitHub Web Interface + +1. Navigate to your repository on GitHub +2. Click on **Settings** (requires admin permissions) +3. In the left sidebar, click **Branches** +4. Under "Branch protection rules", click **Add rule** +5. Configure the following settings: + + **Branch name pattern**: `main` (or `master` if that's your default branch) + + **Protect matching branches**: + - ✅ **Require a pull request before merging** + - ✅ Require approvals (optional, recommended: 1) + - ✅ **Require status checks to pass before merging** + - ✅ Require branches to be up to date before merging + - **Status checks that are required**: + - Search for and select: `test (pdflatex, eiti, pol, MasterThesis)` + - Search for and select: `test (pdflatex, eiti, pol, EngineerThesis)` + - Search for and select: `test (lualatex, eiti, pol, MasterThesis)` + - Search for and select: `test (lualatex, eiti, pol, EngineerThesis)` + - Search for and select: `test (pdflatex, meil, pol, MasterThesis)` + - Search for and select: `test (pdflatex, meil, pol, EngineerThesis)` + - Search for and select: `test (lualatex, meil, pol, MasterThesis)` + - Search for and select: `test (lualatex, meil, pol, EngineerThesis)` + - Search for and select: `test (pdflatex, eiti, eng, MasterThesis)` + - Search for and select: `test (pdflatex, eiti, eng, EngineerThesis)` + - Search for and select: `test (lualatex, eiti, eng, MasterThesis)` + - Search for and select: `test (lualatex, eiti, eng, EngineerThesis)` + - Search for and select: `test (pdflatex, meil, eng, MasterThesis)` + - Search for and select: `test (pdflatex, meil, eng, EngineerThesis)` + - Search for and select: `test (lualatex, meil, eng, MasterThesis)` + - Search for and select: `test (lualatex, meil, eng, EngineerThesis)` + + **Additional options** (recommended): + - ✅ **Require conversation resolution before merging** (optional) + - ✅ **Do not allow bypassing the above settings** (recommended) + +6. Click **Create** or **Save changes** + +### Via GitHub CLI (requires admin permissions) + +Replace `{owner}` with your GitHub username/organization and `{repo}` with your repository name: + +```bash +# Example: For repository https://github.com/kuhyx/praca_magisterska +# Replace {owner} with: kuhyx +# Replace {repo} with: praca_magisterska + +gh api repos/{owner}/{repo}/branches/main/protection \ + --method PUT \ + --field required_status_checks[strict]=true \ + --field required_status_checks[contexts][]=test (pdflatex, eiti, pol, MasterThesis) \ + --field required_status_checks[contexts][]=test (pdflatex, eiti, pol, EngineerThesis) \ + --field required_status_checks[contexts][]=test (lualatex, eiti, pol, MasterThesis) \ + --field required_status_checks[contexts][]=test (lualatex, eiti, pol, EngineerThesis) \ + --field required_status_checks[contexts][]=test (pdflatex, meil, pol, MasterThesis) \ + --field required_status_checks[contexts][]=test (pdflatex, meil, pol, EngineerThesis) \ + --field required_status_checks[contexts][]=test (lualatex, meil, pol, MasterThesis) \ + --field required_status_checks[contexts][]=test (lualatex, meil, pol, EngineerThesis) \ + --field required_status_checks[contexts][]=test (pdflatex, eiti, eng, MasterThesis) \ + --field required_status_checks[contexts][]=test (pdflatex, eiti, eng, EngineerThesis) \ + --field required_status_checks[contexts][]=test (lualatex, eiti, eng, MasterThesis) \ + --field required_status_checks[contexts][]=test (lualatex, eiti, eng, EngineerThesis) \ + --field required_status_checks[contexts][]=test (pdflatex, meil, eng, MasterThesis) \ + --field required_status_checks[contexts][]=test (pdflatex, meil, eng, EngineerThesis) \ + --field required_status_checks[contexts][]=test (lualatex, meil, eng, MasterThesis) \ + --field required_status_checks[contexts][]=test (lualatex, meil, eng, EngineerThesis) \ + --field required_pull_request_reviews[required_approving_review_count]=1 \ + --field enforce_admins=true +``` + +## Verification + +Once branch protection is enabled: +1. All pull requests to `main`/`master` will show the required status checks +2. The "Merge" button will be disabled until all 16 CI jobs pass +3. Pull requests must be up-to-date with the base branch before merging + +## Testing Locally + +Before pushing changes, you can test the LaTeX build locally: + +```bash +cd latex +scons generate_tests +scons quick +``` + +This will verify that the basic build works before triggering the full CI matrix. + +## Notes + +- Branch protection rules can only be configured by repository administrators +- The status check names must match exactly as they appear in the GitHub Actions workflow +- Once configured, bypassing these rules requires admin override +- The CI workflow automatically runs on all push and pull request events diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 89c55b6..e8ca0a6 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -35,11 +35,14 @@ jobs: - name: Generate test cases run: scons generate_tests + working-directory: latex - name: Generate PDF file run: cp test/${{matrix.lang}}/${{matrix.faculty}}/${{matrix.thesis}}.textest main.tex && scons all + working-directory: latex - name: Verify build with referential text run: | scons test pdf=build/pdfs/${{matrix.compiler}}.pdf \ ref=test/${{matrix.lang}}/${{matrix.faculty}}/${{matrix.thesis}}_${{matrix.compiler}}.txt + working-directory: latex diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..5e748c7 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,53 @@ +# Pre-commit configuration for WUT-Thesis +# See https://pre-commit.com for more information +# See https://pre-commit.com/hooks.html for more hooks + +repos: + # General file checks + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: trailing-whitespace + exclude: '\.(tex|bib)$' # LaTeX may need trailing whitespace + - id: end-of-file-fixer + exclude: '\.(pdf|png|jpg|jpeg)$' + - id: check-yaml + args: ['--unsafe'] # Allow custom YAML tags in GitHub workflows + - id: check-added-large-files + args: ['--maxkb=5000'] # Warn about files larger than 5MB + - id: check-merge-conflict + - id: mixed-line-ending + + # YAML linting for GitHub Actions workflows + - repo: https://github.com/adrienverge/yamllint + rev: v1.33.0 + hooks: + - id: yamllint + args: ['-d', '{extends: default, rules: {line-length: {max: 120}, document-start: disable}}'] + files: ^\.github/workflows/.*\.ya?ml$ + +# Optional: Uncomment to enable LaTeX-specific checks +# Note: These require additional dependencies (chktex, lacheck) +# - repo: https://github.com/jonasbb/pre-commit-latex-hooks +# rev: v1.4.0 +# hooks: +# - id: american-eg-ie +# - id: cleveref-capitalization +# - id: consistent-spelling +# args: +# - '--emph=et al.,emph=etc.' +# - id: csquotes +# - id: ensure-labels-for-sections +# - id: no-space-in-cite +# - id: tilde-cite +# - id: unique-labels + +# To install pre-commit hooks, run: +# pip install pre-commit +# pre-commit install +# +# To run manually on all files: +# pre-commit run --all-files +# +# To update hooks to latest versions: +# pre-commit autoupdate diff --git a/latex/README.md b/latex/README.md index 2d310af..46e77fe 100644 --- a/latex/README.md +++ b/latex/README.md @@ -110,5 +110,15 @@ Preferowanym kanałem zgłaszania problemów z szablonem są [issues-y][ref:issu ## Dla deweloperów Informacje dla osób zainteresowanych rozwijaniem szablonu znajdują się w [encyklopedii projektu][ref:wiki]. +### CI/CD i Branch Protection +Repozytorium posiada automatyczne testy CI sprawdzające poprawność kompilacji dla wszystkich kombinacji wydziałów, języków i typów prac. Aby zapewnić jakość kodu: + +- **Branch Protection**: Zobacz [../.github/BRANCH_PROTECTION.md](../.github/BRANCH_PROTECTION.md) dla instrukcji konfiguracji wymaganych testów przed mergowaniem do `main`/`master` +- **Pre-commit hooks**: Zainstaluj lokalne pre-commit hooks, aby wykrywać problemy przed pushowaniem: + ```bash + pip install pre-commit + pre-commit install + ``` + ## Uwagi Copyleft © [Artur M. Brodzki](https://github.com/ArturB) 2019-2023. Loosely based on [EiTI-Szablon](https://github.com/pwozniak/EiTI-Szablon) by [Piotr Woźniak](https://github.com/pwozniak). All wrongs reserved. diff --git a/requirements.txt b/requirements.txt index 945a6a6..6f37da5 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,4 @@ Jinja2>=3.0.0 pdfminer.six>=2021 SCons>=4.0.0 +pre-commit>=3.0.0