CONTRIBUTING.md

CONTRIBUTING.md (3865B)
      1 # Contributing to cdnV2
      2 
      3 Thanks for helping out! Bug reports, fixes, docs and well-scoped features are all welcome.
      4 
      5 By participating you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md). To report a security
      6 problem, please use [SECURITY.md](SECURITY.md) rather than a public issue.
      7 
      8 ## Before you start
      9 
     10 - **Bugs and small fixes:** go ahead and open a pull request.
     11 - **New features or larger changes:** open an issue first so we can agree on the approach before you
     12   spend time on it.
     13 - **Looking for something to do?** Issues labelled `good first issue` are a good place to begin.
     14 
     15 ## Development setup
     16 
     17 ```bash
     18 git clone https://github.com/<you>/cdnV2.git
     19 cd cdnV2
     20 python -m venv .venv && source .venv/bin/activate
     21 pip install -r requirements.txt
     22 cp .env.example .env     # fill in HF_BUCKET_ID and HF_TOKEN
     23 set -a; . ./.env; set +a
     24 uvicorn app.main:app --reload
     25 ```
     26 
     27 Use a **throwaway Hugging Face bucket and token** for development, never production credentials.
     28 Run the app from the repository root — templates are loaded from `app/templates` relative to it.
     29 
     30 ## Checks
     31 
     32 CI runs these on every pull request; please run them locally first:
     33 
     34 ```bash
     35 pip install ruff
     36 ruff check --select E9,F63,F7,F82 app   # syntax errors and undefined names
     37 python -m compileall -q app
     38 npm install --no-save --no-package-lock jsdom@30.1.2 @hotwired/turbo@8.0.4   # test-only; nothing is added to the repo
     39 node --test tests/*.test.js              # JS unit + jsdom tests (prefetcher, instant folders), Node 20+
     40 HF_BUCKET_ID=ci/x python tests/test_fast_tree.py   # a locally built folder page must equal the server's
     41 HF_BUCKET_ID=ci/x python tests/test_server_fastpaths.py   # offline checks for the caching/gzip/listing fast paths
     42 docker build -t cdnv2 .                  # the image must still build
     43 ```
     44 
     45 There is no full Python test suite yet; `tests/test_server_fastpaths.py` is a plain script (no pytest)
     46 that runs against a fake bucket. If you add logic that can be tested without network access (parsing,
     47 validation, rate limiting), adding a test alongside it is very much appreciated.
     48 
     49 ## Pull requests
     50 
     51 1. Branch from `main` with a descriptive name (`fix-zip-empty-folder`, `docs-self-hosting`).
     52 2. Keep each PR focused on one change; avoid unrelated reformatting.
     53 3. Match the surrounding code style. The code is plain, readable Python with short comments that
     54    explain *why*, not *what*.
     55 4. Update the README, `.env.example` and the in-app documentation pages if behaviour or configuration
     56    changes.
     57 5. Fill in the pull request template, including how you tested the change.
     58 
     59 ## Ground rules
     60 
     61 - **Never commit secrets.** No tokens, keys or `.env` files. If you accidentally push one, revoke it
     62   immediately and tell a maintainer.
     63 - **Keep configuration in environment variables**, with defaults that are safe for a new deployment.
     64 - **Preserve backwards compatibility** for existing deployments unless the change is clearly marked as
     65   breaking.
     66 - **Be careful with anything that touches uploads, rate limits, admin or the GitHub OIDC check** — these
     67   are the security boundary of the project. Explain your reasoning in the PR.
     68 
     69 ## License of contributions
     70 
     71 This project is licensed under the [MIT License](LICENSE). By submitting a contribution you agree that
     72 it is licensed under the same terms, and that you have the right to submit it.
     73 
     74 ## Changing the folder page markup
     75 
     76 The folder listing's HTML lives in `app/templates/_listing.html` (Jinja macros) and is used both by the
     77 server and, via `/api/shell`, by the browser's instant-folder navigation. Edit the macros there, not
     78 inline in `index.html`. If you add something that depends on the folder's contents, the client has to be
     79 able to fill it in from the file tree; `python tests/test_fast_tree.py` fails with a diff if the locally
     80 built page no longer equals the server-rendered one.