vinez/bambuddy
1
0
Fork 0
mirror of https://github.com/maziggy/bambuddy.git synced 2026-08-11 00:30:12 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated CONTRIBUTING.md

Browse source
This commit is contained in:
maziggy 2026-04-24 09:47:45 +02:00
parent 0cf7a11f46
commit 1b284a9e39
1 changed files with 5 additions and 25 deletions
Download patch file Download diff file Expand all files Collapse all files

30
CONTRIBUTING.md
View file

@ -61,37 +61,18 @@ Features and user-visible behavior changes **must** include matching documentati
1. Open your code PR here in `bambuddy`
2. Open companion PR(s) in `bambuddy-wiki` and/or `bambuddy-website`
3. **Link the companion PR(s) in the code PR description** (the PR template has a dedicated section)
4. Review the Cloudflare Pages **preview URLs** (posted as comments on the docs PRs) before merging
5. Merge the PRs together — usually code first, then docs, unless the docs reference new things that don't exist yet
4. Merge the PRs together — usually code first, then docs, unless the docs reference new things that don't exist yet
If your change truly doesn't need docs (internal refactor, silent bug fix), say so in the PR description and give a one-line reason.
### Previews before you merge
Both docs repos are connected to [Cloudflare Pages](https://pages.cloudflare.com/). Every PR triggers an automatic build and deploys the result to a throwaway preview URL, so you can see your changes rendered on the real site before merging.
Clone the docs repo and run it locally to see your changes rendered with the real theme before opening the PR:
**What you'll see on a docs PR**:
- **Wiki** (`bambuddy-wiki`) — `pip install -r requirements.txt && mkdocs serve` — live-reload on `http://localhost:8000`
- **Website** (`bambuddy-website`) — static HTML/CSS, open the changed file directly or serve with `python -m http.server`
1. Within ~30 seconds of pushing, a GitHub check appears:
`Cloudflare Pages — Deploying...` (yellow dot).
2. After the build completes (~1 minute for the wiki, ~10 seconds for the website), the check turns green and `cloudflare-pages[bot]` posts a comment with a preview URL like:
> Deploying bambuddy-wiki with Cloudflare Pages
> Preview: https://<branch-name>.bambuddy-wiki.pages.dev/
3. Click the URL — you'll see the full rendered site with your changes, on the real theme, with working navigation, images, and links.
4. Review the preview like you would the production site. Catch broken links, layout regressions, typos, missing images.
5. If the preview looks right, merge the PR. If not, push more commits to the same branch — the preview auto-rebuilds on each push.
**If the build fails**:
- The check turns red and no preview URL is posted.
- Click the check's "Details" link to see the build log.
- Common causes: MkDocs YAML syntax error, broken image path, unclosed HTML tag. Fix in another commit, the build retries automatically.
**Preview URL quirks to know**:
- Previews are **publicly accessible** — fine for open-source docs, but don't paste drafts you wouldn't want strangers to see.
- Preview URLs persist for a while after the PR is merged or closed, but Cloudflare eventually cleans them up.
- Previews build from the **PR branch**, not from `main` — so you're always looking at exactly what will be merged.
Review like you would the production site. Catch broken links, layout regressions, typos, missing images. If it looks right, open the PR.
### Editing docs without a local clone
@ -99,7 +80,6 @@ Both docs repos can be edited directly in the browser, no `git clone` required:
- **GitHub web editor** — click the pencil icon on any file in the repo
- **github.dev** — press `.` (period) on any repo page to open VS Code in your browser, with multi-file editing and syntax highlighting
- **Cloudflare Pages previews** — every PR gets a live preview URL auto-posted to the PR as a comment; click it to see your changes rendered on the real site
## Getting Started