|
1 | | -# OTE Template |
| 1 | +# <Your community name> |
2 | 2 |
|
3 | 3 | <!-- |
4 | | -Uncomment these once you've finished the setup below, replacing |
5 | | -your-user/your-repo with your fork (and the Pages URL in the third one): |
| 4 | +Uncomment these once you've finished SETUP.md, replacing your-user/your-repo |
| 5 | +with your fork (and the Pages URL in the third one): |
6 | 6 |
|
7 | 7 | [](https://github.com/your-user/your-repo/actions/workflows/validate.yml) |
8 | 8 | [](https://github.com/your-user/your-repo/actions/workflows/publish.yml) |
9 | 9 | [](https://opentechevents.org/spec/) |
10 | 10 | --> |
11 | 11 |
|
12 | | -Fork this repository and get, with nothing but GitHub and GitHub Pages: |
| 12 | +<!-- New fork? The one-time setup guide is in SETUP.md. --> |
13 | 13 |
|
14 | | -- Your community's **[OTE](https://opentechevents.org) event feed** published at a public URL. |
15 | | -- **iCalendar (`feed.ics`)** and **RSS (`feed.xml`)** exports, rebuilt automatically on every change. |
16 | | -- A minimal **dashboard** linking to the central OTE tools (editor, import, publish). |
| 14 | +Describe what type of events this feed includes — talks, meetups, workshops, |
| 15 | +conferences… |
17 | 16 |
|
18 | | -Your data stays in **your** repository, as plain JSON, under an open license. |
19 | | -No lock-in: the ICS/RSS exports mean you can leave anytime and take everything with you. |
| 17 | +**👉 [See what's coming up](https://your-user.github.io/your-repo/)** |
20 | 18 |
|
21 | | -## What's in this repo |
| 19 | +## Subscribe |
22 | 20 |
|
23 | | -``` |
24 | | -├── events/*.json ← your events (one file per event — starts empty, |
25 | | -│ see events/README.md) |
26 | | -├── ote.config.json ← your configuration (feed title, description…) |
27 | | -├── docs/index.html ← static dashboard (links to central tools) |
28 | | -└── .github/workflows/ ← thin workflows calling reusable workflows |
29 | | - in OpenTechEvents/ote-tools |
30 | | -``` |
| 21 | +| Format | URL | For | |
| 22 | +| --- | --- | --- | |
| 23 | +| iCalendar | [`feed.ics`](https://your-user.github.io/your-repo/feed.ics) | Add it to Google Calendar, Apple Calendar or Outlook — new events show up on their own | |
| 24 | +| RSS | [`feed.xml`](https://your-user.github.io/your-repo/feed.xml) | Follow it from any feed reader | |
| 25 | +| JSON | [`feed.json`](https://your-user.github.io/your-repo/feed.json) | Build something with it — the machine-readable [OTE](https://opentechevents.org/spec/) feed | |
31 | 26 |
|
32 | | -That's all. Validation, exports and the editor UI live in |
33 | | -[OpenTechEvents/ote-tools](https://github.com/OpenTechEvents/ote-tools) and are |
34 | | -consumed via reusable workflows — improvements reach your fork without you |
35 | | -touching anything. |
| 27 | +For the calendar formats, look for "subscribe by **URL**" (not "import |
| 28 | +file") and paste the `feed.ics` link — that way it stays in sync instead of |
| 29 | +freezing at import time. |
36 | 30 |
|
37 | | -## Get started |
| 31 | +## Reuse the data |
38 | 32 |
|
39 | | -### 1. Fork |
| 33 | +Event data in this repository is published under the license declared in |
| 34 | +[`ote.config.json`](ote.config.json). Building a directory, a newsletter or |
| 35 | +your own aggregator? Take what you need — republishing this feed is itself a |
| 36 | +form of supporting this community. |
40 | 37 |
|
41 | | -Click **Fork** on this repository. Fork — not "Use this template" — so you can |
42 | | -later pull upstream improvements to the dashboard and workflows: |
| 38 | +## Contributing |
43 | 39 |
|
44 | | -``` |
45 | | -git remote add upstream https://github.com/OpenTechEvents/ote-template |
46 | | -git pull upstream main |
47 | | -``` |
48 | | - |
49 | | -### 2. Enable workflows |
50 | | - |
51 | | -GitHub disables Actions on forks by default. In your fork, open the |
52 | | -**Actions** tab and click **"I understand my workflows, go ahead and enable |
53 | | -them"**. Without this, nothing gets validated or published. |
54 | | - |
55 | | -### 3. Enable GitHub Pages |
56 | | - |
57 | | -In your fork: **Settings → Pages → Source: GitHub Actions**. |
58 | | - |
59 | | -Once the first deploy finishes, link the site from your repo so visitors find |
60 | | -it: repo home → **About** (gear icon) → check **"Use your GitHub Pages |
61 | | -website"**. |
62 | | - |
63 | | -**Custom domain?** If your Pages are served from your own domain instead of |
64 | | -`*.github.io`, the dashboard can't detect the repository from the URL. Create |
65 | | -a `docs/config.js` with one line: |
66 | | - |
67 | | -```js |
68 | | -window.OTE_REPO = "your-user/your-repo"; |
69 | | -``` |
70 | | - |
71 | | -### 4. Enable issues (optional, recommended) |
72 | | - |
73 | | -GitHub disables Issues on forks by default. If you want the community to be |
74 | | -able to report mistakes or propose events — and to use the OTE editor's |
75 | | -"propose change" flow, which delivers changes as prefilled issues — enable |
76 | | -them: **Settings → General → Features → Issues**. |
77 | | - |
78 | | -Then create the label the flow depends on — forks don't inherit labels, and |
79 | | -GitHub silently ignores missing labels declared in issue forms, so without it |
80 | | -proposed events never become pull requests. In your fork: **Issues → Labels → |
81 | | -New label**, name it exactly `ote-event`. The propose-event issue form applies |
82 | | -it, and the issue-to-pr workflow only reacts to issues carrying it. |
83 | | - |
84 | | -Finally, let Actions open the pull request: **Settings → Actions → General → |
85 | | -Workflow permissions → check "Allow GitHub Actions to create and approve pull |
86 | | -requests"**. Without this, a proposed event validates and its branch is pushed, |
87 | | -but the workflow can't open the PR. |
88 | | - |
89 | | -This template ships a [CONTRIBUTING.md](CONTRIBUTING.md) that explains the |
90 | | -contribution flow to visitors. Adapt it to your community, or delete it if |
91 | | -you don't want contributions. |
92 | | - |
93 | | -### 5. Edit `ote.config.json` |
94 | | - |
95 | | -Set your feed's `title`, `description` and `url` (your community's website). |
96 | | - |
97 | | -The `license` applies to your event *data*, not to the events. The template |
98 | | -defaults to [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/) |
99 | | -(public domain — most permissive, anyone can republish your events, which is |
100 | | -the point of a feed). If you want attribution, use |
101 | | -[CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). Any SPDX |
102 | | -identifier or URL is accepted. |
103 | | - |
104 | | -### 6. Add your events |
105 | | - |
106 | | -Add one JSON file per event to [events/](events/) — the full field reference |
107 | | -is at [opentechevents.org/spec](https://opentechevents.org/spec/). Minimal |
108 | | -event: |
109 | | - |
110 | | -```json |
111 | | -{ |
112 | | - "specVersion": "0.3.0", |
113 | | - "id": "https://your-community.example/events/2026-09-meetup", |
114 | | - "name": "September meetup", |
115 | | - "startDate": "2026-09-24T19:00", |
116 | | - "timezone": "Europe/Madrid", |
117 | | - "license": "CC0-1.0" |
118 | | -} |
119 | | -``` |
120 | | - |
121 | | -File names are free-form — any `*.json` under `events/` is picked up. Naming |
122 | | -them `YYYY-MM-name.json` makes them sort chronologically, but nothing depends |
123 | | -on it: an event's identity is its `id` field, not its file name. |
124 | | - |
125 | | -Every push validates your events and, if valid, rebuilds and redeploys your |
126 | | -site: dashboard + `feed.json` + `feed.ics` + `feed.xml` at |
127 | | -`https://<user>.github.io/<repo>/`. Deploys take a couple of minutes. |
128 | | - |
129 | | -### 7. Make your feed discoverable |
130 | | - |
131 | | -Add this to the `<head>` of your community's website (if you have one): |
132 | | - |
133 | | -```html |
134 | | -<link rel="alternate" type="application/ote+json" |
135 | | - href="https://<user>.github.io/<repo>/feed.json"> |
136 | | -``` |
137 | | - |
138 | | -### 8. Register as an adopter |
139 | | - |
140 | | -Add your community to the adopters list in |
141 | | -[opentechevents-spec](https://github.com/OpenTechEvents/opentechevents-spec) so |
142 | | -directories and users can find your feed. |
143 | | - |
144 | | -### 9. Turn on the README badges (optional) |
145 | | - |
146 | | -Near the top of this file, uncomment the `Validate`/`Publish`/`OTE spec` |
147 | | -badges and replace `your-user/your-repo` with your fork. |
148 | | - |
149 | | -## Editing events |
150 | | - |
151 | | -Phase 1 is hand-edited JSON — the workflows validate every push and pull |
152 | | -request, so mistakes can't reach your published feed. The **editor** linked |
153 | | -from your dashboard (create/edit events via a form, proposed as a PR to your |
154 | | -repo) is coming in phase 2. |
155 | | - |
156 | | -**Propose an event without touching JSON**: anyone can fill in the |
157 | | -[OTE editor](https://tools.opentechevents.org/editor?repo=your-user/your-repo) |
158 | | -(replace `your-user/your-repo` with your fork, or just follow the link from |
159 | | -your dashboard). It generates the event JSON and opens a prefilled issue in |
160 | | -your repo; a workflow validates it and turns it into a pull request for you |
161 | | -to review and merge. No git, no JSON editing, no write access needed. |
162 | | - |
163 | | -## Updates |
164 | | - |
165 | | -The thin workflows track `OpenTechEvents/ote-tools@main` (pinned to `@v1` once |
166 | | -stable), so validation and export improvements arrive automatically. For the |
167 | | -few files that live here (dashboard, workflows), pull from upstream now and |
168 | | -then: |
169 | | - |
170 | | -``` |
171 | | -git pull upstream main |
172 | | -``` |
173 | | - |
174 | | -## Using an AI coding assistant on your fork |
175 | | - |
176 | | -If you use Claude Code, Codex, Copilot or similar to help manage your fork, |
177 | | -paste this into whichever instructions file it reads (`CLAUDE.md`, `AGENTS.md`, |
178 | | -`.github/copilot-instructions.md`…) — it keeps the assistant from "helpfully" |
179 | | -adding logic that belongs in `ote-tools` instead of here: |
180 | | - |
181 | | -``` |
182 | | -This is a template repo that community organizers fork. It should contain |
183 | | -ONLY: events/*.json (your data), ote.config.json (your configuration), docs/ |
184 | | -(a minimal static dashboard), and thin workflows that call reusable workflows |
185 | | -in OpenTechEvents/ote-tools. |
186 | | -
|
187 | | -It must NOT contain validation/export/UI logic — that lives in |
188 | | -OpenTechEvents/ote-tools. If a task asks you to add logic here, that's a sign |
189 | | -something is wrong: stop and ask before proceeding. |
190 | | -
|
191 | | -The workflows reference OpenTechEvents/ote-tools/.github/workflows/*.yml@main |
192 | | -(will pin to @v1 once stable). |
193 | | -
|
194 | | -Keep this repo simple enough that an organizer can understand it in five |
195 | | -minutes. |
196 | | -
|
197 | | -Official language: English. All documentation, code comments, names, |
198 | | -commit/PR messages, UI text and repo content are written in English, even if |
199 | | -your own prompts are in another language. |
200 | | -``` |
201 | | - |
202 | | -## License |
203 | | - |
204 | | -Template files (this README, `ote.config.json`'s placeholders): |
205 | | -[CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/). |
206 | | -Your own data: whatever `license` you declare in `ote.config.json` and your events. |
| 40 | +Found a mistake, or want to add an event? See |
| 41 | +[CONTRIBUTING.md](CONTRIBUTING.md). |
0 commit comments