From e49b0441d8073688fa9e8599732ac9970ce5ac42 Mon Sep 17 00:00:00 2001 From: Derek Lewis Date: Tue, 18 Aug 2026 02:12:22 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=E2=99=BB=EF=B8=8F=EF=BC=9Arewrite?= =?UTF-8?q?=20the=20README=20for=20a=20newcomer?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README explained what the portal was for but never said how to run it, so the one thing a new contributor needs first was the thing it left out. It gains a quick start, and a table of where things live. Two errors go with it. The SDK reference documentation was still called IDK, a name we have retired. And five link definitions pointed at github.com/OpenINF/open.inf.is, a repository that does not exist, so Roadmap, Issue Tracker, Changelog, Credits, and "open an issue" were all 404s. package.json named that repository too, and now names this one. The file states no version, no port, and no count. Those are the facts that go stale, and this project has been bitten by exactly that, so it points at package.json rather than quoting it and lets `pnpm start` print its own address. The tagline is new, in the README and package.json alike. The old one reached for a joke about a static site and landed on a list the next paragraph already makes. A portal, said plainly, is a front door. No full stop, because it is a title, and the handbook says a title does not take one. The portal's infancy is noted in a sentence of its own. It belongs to the portal rather than to whoever maintains it, and gives a reader something to do with a rough edge on finding one. The license prose became a table, and the Netlify badge became the two GitHub Actions workflows that gate and publish this repository. Signed-off-by: Derek Lewis Assisted-by: Claude-Code:claude-opus-5 --- README.md | 122 ++++++++++++++++++++++++++++++++++----------------- package.json | 4 +- 2 files changed, 84 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index a14681636..6cef394e6 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,87 @@ ## `open.inf.is` -> ⚡🐋 The OpenINF portal, other static resources, and more static electricity +> The front door to everything OpenINF makes + +[![Lint and test][lint-badge-img]][lint-badge-url] +[![Deploy][deploy-badge-img]][deploy-badge-url]
-[!['Netlify Status: Dynamic'][netlify-badge-img]][netlify-badge-url] +The source of the OpenINF portal: the community website, the news archive, the +OpenINF SDK reference documentation, and the style handbook. One [Eleventy][] +build serves them all. + +The portal is in its infancy, so expect gaps and rough edges. Finding one is a +good reason to open a pull request. + +

+ +### Quick start
-The high-level goal of this project is to build and maintain a community portal -that serves content and assets. Although this portal is still in its infancy, it -is intended to support a separation of concerns between hosting our community -website, SDK documentation, and more. We are constantly working to improve this -work, so please feel free to contribute if you notice any omissions or errors. +Open the repository in the [dev container][] and the toolchain is already +installed. Otherwise, install Node and pnpm at the versions [package.json][] +pins. -Thanks! +```console +pnpm install +pnpm start +``` + +`pnpm start` prints the address to open, and rebuilds as you edit. `pnpm build` +makes a production build, and `pnpm test` runs the checks a pull request has to +pass.

---- +### Where things live
-### Contributing +| Path | What is there | +| :------------------------ | :------------------------------------ | +| `collections/_pages/` | Home, about, docs, and news pages | +| `collections/_posts/` | The news archive, one file per entry | +| `collections/_docs/` | Documentation, and the style handbook | +| `_layouts/`, `_includes/` | Liquid templates and partials | +| `_assets/` | Sass, browser JavaScript, and images | +| `build/` | The build and verify tasks | -Pull requests are welcome. For major changes, please open an issue first to -discuss what you would like to change. If for whatever reason you spot something -to fix but cannot patch it yourself, please [open an issue][]. +The code of conduct, contributing guide, security policy, and support document +are not edited here. They come from [OpenINF/.github][] as the site builds. + +

+ +### Contributing
+Pull requests are welcome. A typo fix needs no ceremony; anything larger is +worth an issue first, so nobody writes the same change twice. + +Two documents are worth reading beforehand: the [contributing guide][], and the +[style handbook][], which covers prose, code samples, and commit messages. + +If you spot something to fix but cannot patch it yourself, [open an issue][]. + +

+ ### License -It is essential always to read the license for all code and content in question. -Each source code and content directory typically contains the appropriate -license file(s) for that directory's source code and/or content. The code and -content files themselves also typically contain licensing and authorship -metadata. +
+ +| What | License | +| :----------------------------- | :----------------------------------- | +| Source code | `MIT OR Apache-2.0 OR BlueOak-1.0.0` | +| OpenINF SDK reference docs | CC BY-NC-SA 4.0 | +| Code samples inside those docs | 0BSD | +| Style handbook | CC BY-SA 4.0 | -Most of the repository's source code is permissively licensed under MIT, Apache -2.0, or Blue Oak 1.0.0. The IDK reference documentation content uses the CC -BY-NC-SA 4.0 license, while the embedded source code snippets and examples use -the public domain equivalent 0BSD license. The collection of documents -comprising our style guide handbook uses the CC BY-SA 4.0 license. +Read the license that applies before reusing anything here, because source, +docs, and the handbook do not share one. Source files name theirs in an +`@license` tag, and the docs and the handbook each keep the full text beside +them.

@@ -75,25 +114,28 @@ comprising our style guide handbook uses the CC BY-SA 4.0 license.

+ -[Roadmap]: https://github.com/OpenINF/open.inf.is/issues 'Roadmap' +[Changelog]: https://github.com/OpenINF/openinf.github.io/commits/live 'Changelog' +[Credits]: https://github.com/OpenINF/openinf.github.io/graphs/contributors 'Credits' [Development]: ./collections/_docs/README.md 'Development' -[Issue Tracker]: https://github.com/OpenINF/open.inf.is/issues 'Issue Tracker' -[Changelog]: https://github.com/OpenINF/open.inf.is/commits/live 'Changelog' -[Credits]: https://github.com/OpenINF/open.inf.is/graphs/contributors 'Credits' -[project-type-badge--shields]: - https://img.shields.io/badge/type-prototype-blue.svg -[prototyping-scheme-badge--shields]: - https://img.shields.io/badge/scheme-evolutionary-blue.svg -[project-status-badge--shields]: - https://img.shields.io/badge/status-under%20construction-yellow.svg -[open an issue]: https://github.com/OpenINF/open.inf.is/issues -[netlify-badge-url]: - https://app.netlify.com/sites/gh-pages-openinf/deploys?branch=live - 'Netlify Status: Dynamic' -[netlify-badge-img]: - https://api.netlify.com/api/v1/badges/d7db7490-f2de-40c6-9236-ce4fcbdaeafd/deploy-status?branch=live - 'Netlify Status: Dynamic' +[Eleventy]: https://www.11ty.dev/ +[Issue Tracker]: https://github.com/OpenINF/openinf.github.io/issues 'Issue Tracker' +[OpenINF/.github]: https://github.com/OpenINF/.github +[Roadmap]: https://github.com/OpenINF/openinf.github.io/issues 'Roadmap' +[contributing guide]: https://github.com/OpenINF/.github/blob/HEAD/CONTRIBUTING.md +[dev container]: ./.devcontainer/devcontainer.json +[open an issue]: https://github.com/OpenINF/openinf.github.io/issues +[package.json]: ./package.json +[style handbook]: ./collections/_docs/handbook/style/ +[deploy-badge-img]: https://github.com/OpenINF/openinf.github.io/actions/workflows/deploy.yml/badge.svg?branch=live +[deploy-badge-url]: https://github.com/OpenINF/openinf.github.io/actions/workflows/deploy.yml +[lint-badge-img]: https://github.com/OpenINF/openinf.github.io/actions/workflows/lint-and-test.yml/badge.svg +[lint-badge-url]: https://github.com/OpenINF/openinf.github.io/actions/workflows/lint-and-test.yml +[project-status-badge--shields]: https://img.shields.io/badge/status-under%20construction-yellow.svg +[project-type-badge--shields]: https://img.shields.io/badge/type-prototype-blue.svg +[prototyping-scheme-badge--shields]: https://img.shields.io/badge/scheme-evolutionary-blue.svg + diff --git a/package.json b/package.json index f2b9430fe..6b41b3562 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@openinf/portal", "author": "The OpenINF Authors & Friends", "private": "true", - "description": "The OpenINF portal, other static resources, and more static electricity", + "description": "The front door to everything OpenINF makes", "packageManager": "pnpm@11.21.0", "engines": { "node": "24.19.0", @@ -16,7 +16,7 @@ "./build/utils": "./build/utils.mts" }, "homepage": "open.inf.is", - "repository": "OpenINF/open.inf.is", + "repository": "OpenINF/openinf.github.io", "scripts": { "build": "nps build", "start": "nps",