diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index e8350138b..981225f64 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -44,6 +44,11 @@ # instructions. These carry legal and financial statements. /content/pybcn_association/ @pybcn/web +# The code of conduct itself. The page under content/pybcn_association/ +# renders this file through the repo-markdown shortcode, so the legal text +# lives at the root and not in content/, and the rule above does not reach it. +/CODE_OF_CONDUCT.md @pybcn/web + # The custom domain of the GitHub Pages site. A change to this file points # pybcn.org somewhere else. /CNAME @pybcn/web diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..943307efd --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,167 @@ +# AGENTS.md + +Guidance for AI coding agents working on pybcn.org, the website of Associació +Python Barcelona. + +Read [CONTRIBUTING.md](CONTRIBUTING.md) as well. This file covers only what an +agent gets wrong that a human would not, and what this repository does +differently from a default Hugo site. + +## Build and run + +```sh +bin/install # downloads the pinned Hugo binary, verifies its SHA256 +bin/serve # dev server, Hugo's default :1313 +bin/build # writes to docs/ +bin/hugo --quiet -d /tmp/out # the binary directly +``` + +**The Hugo binary lives at `bin/hugo` and is gitignored.** `bin/helpers` prefers +it over anything on `$PATH`, and checks the version from `.hugo-version`. + +**Do not `pip install hugo`.** That PyPI package now requires a Go toolchain and +fails. `bin/install` fetches the official release binary instead. + +A clean build produces **109 HTML pages**: 53 Hugo-generated and 56 copied +from `static/archives/`. Recount rather than trusting this line: the number +moves with the content. It was 317 until #202 stopped publishing the 206 +person and sponsor pages that nothing linked to, which is how quickly a +figure like this goes stale. + +## Traps that have already cost time + +**TOML key placement.** `config.toml` ends with nested `[params.social_items...]` +tables. A key appended at the end of the file lands **inside the last table** and +silently does nothing. Put top-level keys near `theme =`, and verify by building +and checking the output, not by reading the file. + +**`merge.ff = only`.** Any local merge needs `--no-ff`. A failed merge here reports +"Not possible to fast-forward", which is not a conflict. + +**`unsafe=true` in `[markup.goldmark.renderer]`.** Raw HTML in front matter +and page bodies renders unescaped. Two content files still carry it, +`content/events/pyday_bcn/pyday_bcn_2018.md` and `pyday_bcn_2019.md`, which +are pre-Hugo programmes pasted in as tables. So **assume any content field +can inject HTML**, and never add a field that reaches a template through +`safeHTML`. `bin/check-html-safety` rejects dangerous markup in content and +`bin/check-rendered` checks the built pages; both run on every pull request. + +**`resources/_gen/` and `docs/` are build output and are gitignored.** They +used to be tracked, so a build dirtied the tree and a pull request carried +hundreds of regenerated files. If `git status` shows either of them, you are +on a branch from before that change. + +**`master` is not a source branch.** It is the built site, force-pushed as an +orphan commit by the deploy workflow. The default branch is **`edition`**. + +**Images in `static/` cannot be processed by Hugo.** They must be under `assets/` +for `resources.Get` and `.Resize` to work. This is why the site once shipped 8.97 +MB of photographs on a single page. + +## Rules that are not style preferences + +These come from decisions with reasons behind them. Breaking them creates a +problem somebody else has to find. + +**Never store a role that can be computed.** `speaker` and `host` are derived from +the talk and meetup records. Writing them into a person's front matter guarantees +they will eventually contradict the data. + +**A person attribution requires human verification.** Talk records carry +`source` and `confidence`. **Only a human-verified record may create a person page +or link a speaker name.** A record with `confidence: medium` or `low` renders the +talk with an "unconfirmed" marker and leaves the speaker name as plain text. + +This is not a style rule. Publishing an unverified claim about a named person +fails the accuracy principle of the GDPR, and the confidence field then documents +that we knew. + +**Never merge two people on a first-name match.** The existing ids include bare +first names (`david`, `alberto`, `jordi`, `ricardo`) that already collide with +fuller names on the site. When in doubt, leave both and flag it. + +**Do not promote hosting to a role.** Meetup's `eventHosts` field is a tool +attribute, not a title. Hosting one meetup is not being an organizer. + +**RSVPs are not attendance.** `attendedCount` is zero on 205 of 207 events, so the +only figure available is who said yes on Meetup. Render it as registrations. + +**No personal data beyond what is already published.** Never render email +addresses, phone numbers, or social handles extracted from old event +descriptions, even though they are present in the source data. Never derive a +person's attributes from the event they spoke at. + +**Person ids** are `firstname-surname`, kebab-case, accents stripped. A rename +carries an `aliases` entry **and** updates every reference in `content/events/` in +the same commit. Skipping the second half silently drops the person from those +pages, and that bug has been live on this site. + +## Commits + +**No AI attribution.** No `Co-Authored-By` trailer, no generated-with footer, no +model byline. Commits read as authored by the person who made them. + +**Never use the em dash character (U+2014).** Use a comma, a colon, parentheses, or +restructure. + +Write in plain, factual English. Say what changed, why, and what you verified. +**If part of the work is unfinished, say so in the commit message**, with what +blocks it. A commit that claims more than it did is worse than one that admits a +gap. + +## Verify, do not assert + +This repository has a history of changes that looked right and were not. The +build succeeding proves very little: a missing sponsor page, a person id that does +not match its filename, and a broken image URL all build cleanly. + +So: + +- Build and grep **the generated HTML**, not the templates. +- Give before and after numbers for anything you claim to have fixed. +- When you cannot verify something without a browser or a screen reader, **say + that** rather than asserting it works. + +Two checkers exist and both are cheap to run: + +```sh +bin/check-content # front matter, ids, cross-references (needs pyyaml) +bin/check-html-safety # dangerous raw HTML in content +``` + +## Things you cannot do + +**Do not push, open pull requests, or comment on GitHub.** Leave your work as a +local branch. Opening it is a human decision, taken per item. + +**Do not change DNS, repository settings, or anything outside the working tree.** + +**Do not install software.** If a task genuinely needs a tool that is absent, say +so and stop, rather than working around it with something that produces a +plausible but different result. + +## Where things are + +| Path | What | +|---|---| +| `content/people/` | One markdown file per person, keyed by `id` | +| `content/events/` | PyDay BCN, PyDataBCN, and other events, with their agendas in front matter | +| `content/sponsors/` | One file per sponsor | +| `themes/pybcn_theme/` | The theme, **vendored in-tree**, not a submodule | +| `themes/pybcn_theme/layouts/partials/` | Most of the interesting template logic | +| `static/archives/` | Verbatim mirrors of pre-Hugo sites, copied unprocessed | +| `data/` | Tables the templates read: `roles.yaml` maps a heading to a role, `role_emoji.yaml` a role to a glyph | +| `bin/` | Setup and build scripts, plus the gitignored Hugo binary | +| `.hugo-version` | The pinned Hugo version, single source of truth | + +The checks, which are what a pull request has to pass: + +| Script | What it rejects | +|---|---| +| `bin/check-content` | A broken reference, a photo that is not square, a source far larger than the build asks for, a field that no longer exists | +| `bin/check-html-safety` | Dangerous raw HTML in content, with an allowlist for the legitimate embeds | +| `bin/check-rendered` | The same, on the built pages, plus any `http://` URL. Run it against a directory you built, never against `public/` while a dev server is writing there | + +The join between a person and an event is `where $pages ".Params.id" "eq" $person` +in `partials/people-grid.html`. That pattern is how everything cross-references, +and it fails silently when an id does not match. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..ff87fee2c --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,35 @@ +# Code of Conduct + +PyBCN is dedicated to providing a respectful, harassment-free community for +everyone. We do not tolerate harassment or bullying of any community member in +any form. This does not only extend to members to local PyBCN communities, +but to anyone who chooses to become involved in the larger PyBCN community of +users, developers and integrators through events or interactions. + +Harassment includes offensive verbal/electronic comments related to personal +characteristics or choices, sexual images or comments in public or online +spaces, deliberate intimidation, bullying, stalking, following, harassing +photography or recording, sustained disruption of talks, IRC chats, electronic +meetings, physical meetings or other events, inappropriate physical contact, or +unwelcome sexual attention. Participants asked to stop any harassing or +bullying behavior are expected to comply immediately. + +If a participant engages in harassing behavior, representatives of the +community may take reasonable action they deem appropriate, including warning +the offender, expulsion from any PyBCN event, or expulsion from mailing +lists, IRC chats, discussion boards and other electronic communications +channels to resolve the issue. This may include expulsion from PyBCN Meetup +group membership. + +If you are being harassed, notice that someone else is being harassed, or have +any other concerns, please act to intercede or ask for help from any member of +the PyBCN community, IRC chat admins, website admins, or +organizers/representatives of any physical events put on under the auspices of +PyBCN. + +This Code of Conduct has been adapted from the +[PyLadies](https://www.pyladies.com/CodeOfConduct/) one, which is licensed +under a +[Creative Commons Attribution-Share Alike 3.0 Unported license](https://creativecommons.org/licenses/by-sa/3.0/), +and is licensed under a +[Creative Commons Attribution-ShareAlike 4.0 International license](https://creativecommons.org/licenses/by-sa/4.0/). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..e6b672f48 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,172 @@ +# Contributing to the PyBCN site + +This repository holds the source of [pybcn.org](https://pybcn.org/), the site +of the Python Barcelona association, built with [Hugo](https://gohugo.io). A +change goes through a pull request against the `edition` branch, and this +guide says how. The [README](README.md) documents the site itself: the content +fields, the layouts, and what each check looks for. + +## Code of conduct + +The PyBCN [Code of Conduct](CODE_OF_CONDUCT.md) applies to every contribution: +a pull request, an issue, a review, and the discussion around them. It is the +same text the site publishes at +[pybcn.org/pybcn_association/coc/](https://pybcn.org/pybcn_association/coc/), +which renders that file. + +## Licence + +The code of the site is under the [MIT License](LICENSE) and the content is +under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). +[LICENSING.md](LICENSING.md) says which paths each one covers, and which paths +are not licensed at all: the photographs of people, the person pages, the +sponsor logos, the association's own logos, the third-party libraries, and the +archived sites. + +A pull request is a contribution under those terms. A change to a template, a +script, or a stylesheet is offered under the MIT License, and a change to the +text of a page is offered under CC BY-SA 4.0. Your own page under +`content/people/` and your photo are different: you keep every right in them, +and you give PyBCN permission to publish them on this site, which you can +withdraw. + +## Which branch + +Open the pull request against `edition`. It is the default branch and it holds +the source. `master` holds the built site: the `github-pages` workflow writes +it on every merge to `edition` and replaces its history each time, so nothing +is edited there, and a change made on `master` is lost on the next deploy. + +## Your own card + +**You do not need Git, GitHub, or any of the rest of this file.** + +If you have spoken at one of our events, or you organise with us, you may have +a card on the [organizers page](https://pybcn.org/pybcn_association/organizers/) +or on the page of the event. Clicking it opens what the site holds about you. +To change any of it, or to have it removed, **send an email to + saying what to change**. That is enough. We do not ask +for identity documents to correct or remove your own name. + +If you would rather do it yourself, every card is a file under +`content/people/`, named after the person. Click the pencil icon on GitHub, +change the text, and GitHub walks you through opening a pull request. + +### What is on your card + +Your name, the role you held, and the events you appeared at. The list of +events is computed from the pages that list you, so it is not edited on your +card: if an event is missing or wrong, tell us and we fix the event page. + +Everything else is yours to give or withhold: + +| Field | What it does | +|---|---| +| `photo` | A square image, under `themes/pybcn_theme/assets/images/people/` | +| `linkedin`, `github`, `twitter`, `site` | Links under your name | +| the body of the file | The bio, one paragraph or several | + +Whoever did not want a photo does not have one, and the card works without it. + +### If you would rather not appear + +Write to and we remove the card. We will not argue +about it. + +Be aware of what removal can and cannot do, because this is a public +repository. We remove the card from the site and from the build, and we ask +search engines and the Internet Archive to drop their copies. We cannot remove +it from the Git history, and we cannot remove copies other people have already +made. + +If that is not acceptable to you, tell us **before** we publish. We would +rather not publish a card than publish one we cannot properly withdraw. + +## Add content without writing code + +Most changes to this site are content: a person, a sponsor, an event. Each one +is a Markdown file with a front matter, and the README documents the fields. +Edit the file on GitHub, or clone the repository and follow the steps below. + +- **A person** (an organizer, a speaker, a mentor): copy a file under + `content/people/` and edit it. The front matter carries `id`, which has to + match the file name, `name`, `photo`, the role at PyBCN, and the links to + the person's own profiles. The bio goes in the body. Leave out any field the + person does not have. The photo goes under + `themes/pybcn_theme/assets/images/people/` and has to be square, see + [Person photos](README.md#person-photos). +- **A sponsor**: run `bin/hugo new sponsors/my-sponsor.md` and fill the four + fields listed in [How to add a new sponsor](README.md#how-to-add-a-new-sponsor). + The logo goes under `themes/pybcn_theme/assets/images/sponsors/`. Then list + the sponsor on the sponsors page, or on the event, that shows it. +- **An event**: copy the previous edition under `content/events/`, for example + `content/events/pyday_bcn/pyday_bcn_2025.md`, and edit it. The sections, the + agenda and the people grids are described in + [Event page](README.md#event-page). An event lists its people and sponsors by + their `id`, so add those files first. + +`bin/check-content` reads every person, sponsor and event file. The pull +request fails when a field is empty, an `id` does not match the file name, a +declared photo is missing, or an event names a person or a sponsor that does +not exist. Run it locally, step 5 below, to see what it would say. + +To report a problem with the site, open an issue and give the URL of the page. + +## Make the change + +Nothing is pushed to `edition` directly. + +1. Clone the repository. `git clone --single-branch --branch edition` is enough + and skips the built site, which lives on its own branch. +2. Run `bin/install`. It downloads the pinned Hugo binary into `bin/hugo` and + verifies its checksum. You do not need Python, Go, or npm for this step. +3. Run `bin/serve` to see the site at `http://localhost:1313` while you work. +4. Make the change. +5. Run the three checks locally, so you find what the pull request would find: + + ``` + pip install pyyaml pillow + bin/check-content + bin/check-html-safety + bin/hugo --minify -D -d public && bin/check-rendered + ``` + + Pillow is only needed for the black and white photo check. Without it the + rest still runs and the check says it was skipped, so a missing Pillow + never fails a build for the wrong reason. + +6. Open the pull request against `edition`. + +## What the pull request goes through + +The `pr-checks` workflow runs the same checks on your branch, plus a build and +a link check. **All of them have to pass**, and one approving review is needed +before the pull request can be merged. + +What each check is for: + +| Check | Fails when | +|---|---| +| Build the site | Hugo cannot build, or emits a warning | +| `bin/check-content` | Front matter does not parse, a person `id` does not match its filename, an id is duplicated, a declared photo is missing, an event references a person or sponsor that does not exist, a social URL has the wrong shape, or a field is empty. It warns, without failing, about a photo that is too small or has no colour | +| `bin/check-html-safety` | Content carries raw HTML that turns a content change into script execution, a redirect, a credential prompt, or a page overlay. See [Content safety check](README.md#content-safety-check) | +| `bin/check-rendered` | The built pages carry that same markup, which catches a template that produces it even when no content file does, or they link to anything over `http`. See [Rendered page check](README.md#rendered-page-check) | +| Check the links | Reported, never blocking, because external sites rate-limit | + +A merge to `edition` deploys the site. The `github-pages` workflow builds it and +publishes the result, so a change is live within a few minutes of the merge. + +## Review by the web team + +`.github/CODEOWNERS` lists the paths where a change reaches every page of the +site, or reaches money, or reaches the deploy: `.github/`, `bin/`, +`config.toml`, `layouts/`, `static/`, `themes/`, `CNAME`, the association +pages under `content/pybcn_association/`, `CODE_OF_CONDUCT.md`, and the +sponsor and event files under `content/sponsors/` and `content/events/`. + +A pull request that touches one of those paths requests a review from +`@pybcn/web` automatically, and the branch protection on `edition` requires +it, so the pull request waits until a member of that team approves it. A +person's file under `content/people/` is not on the list on purpose: a speaker +edits their own page and needs no organizer for that, only the one approving +review every pull request needs. diff --git a/LICENSE b/LICENSE new file mode 100644 index 000000000..559e3176d --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2013-2026 Associació Python Barcelona (PyBCN) and contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/LICENSING.md b/LICENSING.md new file mode 100644 index 000000000..2739d6481 --- /dev/null +++ b/LICENSING.md @@ -0,0 +1,171 @@ +# Licensing + +This repository holds the source of [pybcn.org](https://pybcn.org/), the site +of the Associació Python Barcelona (PyBCN). It holds three kinds of thing, and +one licence does not fit all of them: the code of the site, the text of the +site, and material that the association publishes but does not own. This file +says which licence covers which path, and which paths no licence covers at all. + +GitHub reads the licence of a repository from the `LICENSE` file alone, and a +second licence in that file stops the detection. So `LICENSE` holds the MIT +License text and nothing else, and everything else about licensing is here. + +## Code: MIT License + +The MIT License in [`LICENSE`](LICENSE) covers the code that builds and runs +the site: + +- `layouts/`: the Hugo templates and shortcodes of the site. +- `themes/pybcn_theme/`: the theme. Its templates and partials (`layouts/`), + its stylesheets (`assets/scss/`), the scripts written for this site + (`assets/js/`, except `cookieconsent.min.js`, which is a third-party + library, see below), its `archetypes/`, `theme.toml`, and `README.md`. The + images and the vendored libraries under the theme are listed under + [Not licensed](#not-licensed). +- `bin/`: the build, check, and maintenance scripts. +- `.github/`: the workflows, the code owners, and the Dependabot configuration. +- `config.toml`, `archetypes/`, and the other configuration files at the root + (`.gitignore`, `.hugo-version`, `CNAME`). + +The copyright line in `LICENSE` names the association and the contributors, +and runs from 2013, the year of the first commit. The theme began as a copy of +the `hugo-theme-bootstrap4-blog` theme, which is also under the MIT License; +its notice stays in `themes/pybcn_theme/LICENSE.txt` and covers what remains +of it. + +## Content: CC BY-SA 4.0 + +The text of the site is licensed under the Creative Commons +Attribution-ShareAlike 4.0 International licence (CC BY-SA 4.0): + +- `content/`, except `content/people/`, see [Person pages](#person-pages). +- `README.md` and `CONTRIBUTING.md`. +- `static/humans.txt`. +- `CODE_OF_CONDUCT.md`, an adaptation of the PyLadies code of conduct, see + [Code of conduct](#code-of-conduct) below. + +Deed: + +Legal code: + +Attribute the text to "Python Barcelona (PyBCN), https://pybcn.org/". The +licence requires attribution, a link to the licence, a note of any change, and +the same licence on any adaptation. + +The full legal code is not copied here. Creative Commons keeps the canonical +text at the URL above and says a link to it is enough, and a copy in this +repository would be a second licence text at the root, which is what confuses +the detection described above. + +### Code of conduct + +`CODE_OF_CONDUCT.md` was adapted from the +[PyLadies code of conduct](https://www.pyladies.com/CodeOfConduct/), which is +licensed under +[CC BY-SA 3.0 Unported](https://creativecommons.org/licenses/by-sa/3.0/). The +adaptation is licensed under CC BY-SA 4.0, like the rest of the content, so +the whole repository is on one version of the licence family. + +The licence of the original permits that. Section 4(b) of the +[CC BY-SA 3.0 legal code](https://creativecommons.org/licenses/by-sa/3.0/legalcode) +says that an Adaptation may be distributed under "(ii) a later version of +this License with the same License Elements as this License", and section 1 +names those elements: "Attribution, ShareAlike". CC BY-SA 4.0 is a later +version of that licence, and its License Elements are Attribution and +ShareAlike. The same section 4(b) requires the notices that refer to the +licence of the original to stay intact, so the file keeps its attribution to +PyLadies and the mention of CC BY-SA 3.0, and adds the link to CC BY-SA 4.0. + +ShareAlike is also why the file cannot go under the MIT License: an +adaptation has to stay in the CC BY-SA family, at the same version or a later +one. + +## Not licensed + +The paths below are published on the site but are not covered by either +licence, because the rights in them are not the association's to give. A +licence that promised more than that would tell people they may do things they +may not. + +### Photographs of people + +`themes/pybcn_theme/assets/images/people/` holds one photograph per person on +the site, and `themes/pybcn_theme/assets/images/photos/` holds photographs +taken at PyBCN events. + +The people on this site sent their own photograph for publication on it. +Anyone who did not want one did not send one, and the site shows a silhouette +instead. The association publishes those photographs with the permission of +the people in them, given for that purpose. That permission is not a licence +for anyone else to reuse a photograph, for two reasons: + +- The copyright in a photograph belongs to whoever took it. Giving PyBCN a + copy to publish does not transfer that copyright, so PyBCN has nothing to + sub-license. +- Consent to appear on this site is narrower than a CC BY-SA grant, which + would let a stranger reuse and adapt the image, commercially, for ever. + Under Spanish law (Ley Orgánica 1/1982) the right to one's own image is a + personality right and the consent is revocable, so it cannot become a + perpetual and irrevocable licence, which is what CC BY-SA is. + +So the photographs are not licensed. They are published with the permission +of the people in them, and that permission can be withdrawn. The event +photographs are the same case: the photographer keeps the copyright, and the +people in them keep their image rights. + +### Person pages + +`content/people/` holds one page per person. Each person wrote their own text +and sent it for publication here, so the same reasoning applies: the +association publishes the text, it does not own it, and it cannot license it. + +There is a second reason, specific to these pages. A person can ask the +association to erase their page, and the GDPR (Article 17.2) then obliges the +association to take reasonable steps to tell anyone else holding a copy that +erasure was requested. A licence that invites lawful copies of a person's +entry multiplies the copies the association would have to chase, and works +against the erasure it has to be able to deliver. + +### Sponsor logos + +`themes/pybcn_theme/assets/images/sponsors/` holds the logos of the sponsors. +Each logo is the trade mark of its owner, shown here to acknowledge its +support of PyBCN, with that owner's permission. A trade mark is not the +association's to license, and CC BY-SA 4.0 does not license trade marks in any +case (section 2(b)(2) of the legal code). + +### The association's own marks + +The PyBCN logo and its variants (`themes/pybcn_theme/assets/images/logo.png`, +`themes/pybcn_theme/assets/images/favicon.png`, `static/favicon.ico`, +`static/favicon.png`, and the files under `static/images/backgrounds/`) +identify the association. They are not covered by the content licence: use +them to refer to PyBCN, not to suggest that PyBCN endorses something it has +not seen. The PyLadies name and logo in that same folder are not the +association's. + +### Third-party libraries + +Each of these keeps its own licence, and the notice inside each file stays +with it: + +- `themes/pybcn_theme/assets/vendor/`: jQuery 3.3.1 (MIT), jQuery Easing + 1.4.1 (BSD), Bootstrap 4.0.0 (MIT), and Font Awesome Free 5.8.2 (icons + CC BY 4.0, fonts SIL OFL 1.1, code MIT). +- `themes/pybcn_theme/static/vendor/font-awesome/webfonts/`: the Font Awesome + fonts (SIL OFL 1.1). +- `themes/pybcn_theme/assets/css/bootstrap.min.css`: Bootstrap 4.0.0 (MIT). +- `themes/pybcn_theme/assets/css/cookieconsent.min.css` and + `themes/pybcn_theme/assets/js/cookieconsent.min.js`: the Cookie Consent + library by Osano (MIT). +- `themes/pybcn_theme/assets/images/anon_member.png`: the Font Awesome `user` + icon as a PNG (CC BY 4.0). + +### Archived sites + +`static/archives/` holds copies of two sites as they were published, made +with `bin/archive`: `pybcn.org/`, the previous site of the association, and +`hacktoberfestbarcelona.com/`, the site of Hacktoberfest BCN 2018. They are +kept as a record and are not maintained. Each carries its own photographs, +logos, fonts, and libraries, so nothing under `static/archives/` is licensed by +this repository. diff --git a/README.md b/README.md index fc3fa4070..909dc6e0c 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,8 @@ You can bring a hugo hot reload server using the `bin/serve` script. This will b ### Publishing process -During current implementation phase, the way to publish is to push new commits to the `edition` branch. However this will change in the future, to provide some review step in the publishing process. +A change goes through a pull request against `edition`, and a merge deploys +the site. [CONTRIBUTING.md](CONTRIBUTING.md) has the steps. ### How to add a new sponsor @@ -40,20 +41,10 @@ The MarkDown file for the sponsor will have a FrontMatter section with the follo - `id`: Unique identifier of this sponsor. Should be a string without spaces, preferrably kebab-case. - `name`: Sponsor's name to be shown in all renderings. - `logo_image`: File name for the sponsor logo, which must be under `themes/pybcn_theme/assets/images/sponsors/`. An external URL is not accepted: copy the file into the repository. The template loads it with `resources.Get`, so a file under `static/` is not found, and `bin/check-content` reports it as an error. -- `site`: URL of the sponsor home page. Leave it out when there is nothing to - link to, and the logo renders without a link. It follows the same rules as a - person's `site`, below, and one function checks both. +- `url`: URL for the sponsor web page. +- `twitter`: URL for the sponsor's twitter account. -**Those four are every field a sponsor has.** A sponsor renders as its logo, -linked to its site, and there is no page per sponsor, so nothing else in the -file reaches a reader. `bin/check-content` rejects any other field, and rejects -an empty value: 32 files carried a `twitter`, `linkedin`, `mastodont` or -`instagram` URL that had never been published, written by somebody who expected -it to show. - -There is no detail view, so a body under the front matter is never published. -Put a note about the sponsor in a comment in the front matter instead, where it -is clearly a note. +After this FrontMatter section, any valid MarkDown will be considered generic content to be shown in detail view. Finally, add this sponsor to the sponsors list in the corresponding level of the desired sponsors page, like `content/sponsors/_index.md`, for the main sponsors page; `content/pyladies_bcn/sponsors.md`, for the PyLadies BCN Sponsors' page; or the specific event, if appropriate. @@ -94,47 +85,12 @@ Once the site was archived, you can create a new link in the navigational menu u ### Collaborate -A change to this site goes through a pull request. Nothing is pushed to -`edition` directly. - -1. Clone the repository. `git clone --single-branch --branch edition` is enough - and skips the built site, which lives on its own branch. -2. Run `bin/install`. It downloads the pinned Hugo binary into `bin/hugo` and - verifies its checksum. You do not need Python, Go, or npm for this step. -3. Run `bin/serve` to see the site at `http://localhost:1313` while you work. -4. Make the change. -5. Run the three checks locally, so you find what the pull request would find: - - ``` - pip install pyyaml pillow - bin/check-content - bin/check-html-safety - bin/hugo --minify -D -d public && bin/check-rendered - ``` - - Pillow is only needed for the black and white photo check. Without it the - rest still runs and the check says it was skipped, so a missing Pillow - never fails a build for the wrong reason. - -6. Open the pull request against `edition`. - -The `pr-checks` workflow then runs the same checks on your branch, plus a build -and a link check. **All of them have to pass**, and one approving review is -needed before the pull request can be merged. The paths listed in -`.github/CODEOWNERS` also request a review from the web team automatically. - -What each check is for: - -| Check | Fails when | -|---|---| -| Build the site | Hugo cannot build, or emits a warning | -| `bin/check-content` | Front matter does not parse, a person `id` does not match its filename, an id is duplicated, a declared photo is missing, an event references a person or sponsor that does not exist, a social URL has the wrong shape, or a field is empty. It warns, without failing, about a photo that is too small or has no colour | -| `bin/check-html-safety` | Content carries raw HTML that turns a content change into script execution, a redirect, a credential prompt, or a page overlay | -| `bin/check-rendered` | The built pages carry that same markup, which catches a template that produces it even when no content file does, or they link to anything over `http` | -| Check the links | Reported, never blocking, because external sites rate-limit | - -A merge to `edition` deploys the site. The `github-pages` workflow builds it and -publishes the result, so a change is live within a few minutes of the merge. +The steps to make a change and open a pull request, what the pull request +checks, and which paths wait for a review from the web team are in +[CONTRIBUTING.md](CONTRIBUTING.md), which GitHub links from the pull request +form. It lives there and not here, so there is one description of the process +and not two that drift apart. The two sections below are the detail of the +checks it names. ### Content safety check @@ -179,15 +135,8 @@ decoded, the way a browser does), an inline `