This is an automated email from the ASF dual-hosted git repository.
hubcio pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iggy-website.git
The following commit(s) were added to refs/heads/main by this push:
new 761921dc4 docs: add a CONTRIBUTING guide for the website repo (#69)
761921dc4 is described below
commit 761921dc43de7a59e59dca9a636739ad00f5ec7c
Author: Justin Mclean <[email protected]>
AuthorDate: Tue Sep 1 16:42:59 2026 +1000
docs: add a CONTRIBUTING guide for the website repo (#69)
---
CONTRIBUTING.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 88 insertions(+)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..1af72d914
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,88 @@
+# Contributing to the Apache Iggy website
+
+This repository holds the source of [iggy.apache.org](https://iggy.apache.org):
+the documentation, blog and landing pages. The broker itself lives in
+[apache/iggy](https://github.com/apache/iggy).
+
+## Where things live
+
+| Path | What it holds |
+|------|---------------|
+| `content/docs/**` | Documentation pages, as MDX |
+| `content/blog/**` | Blog posts |
+| `content/docs/**/meta.json` | Sidebar titles and page ordering for each
section |
+| `src/` | Site components and layout |
+| `public/`, `brand-assets/` | Static assets and Apache Iggy brand material |
+
+The site is built with [Fumadocs](https://fumadocs.dev/) on
+[Next.js](https://nextjs.org/) and generates a fully static site.
+
+## Working locally
+
+The required Node version is in `.nvmrc`, and as an `engines` floor in
+`package.json`.
+
+```bash
+npm install
+npm run dev # local server with hot reload
+npm run build # static output in ./out
+```
+
+Run `npm run build` before opening a pull request: MDX that renders in `dev`
+can still fail the static build, most often through a malformed frontmatter
+block or a component that is used but not imported.
+
+Add a new page to the `pages` array of its directory's `meta.json`. Left out,
it
+builds and deploys but never appears in the sidebar.
+
+## Making a change
+
+1. Fork the repository and create a branch off `main`.
+2. Make the change, and check the affected pages in `npm run dev`.
+3. Open a pull request against `main`, describing what was wrong and how you
+ verified the correction.
+
+Small corrections such as a broken link, a stale command or a wrong default
+are welcome as direct pull requests; there is no need to open an issue first.
For
+larger changes such as new pages, restructured navigation or a reorganised
+section, please open an issue to discuss the shape before writing it.
+
+The site is a static export with no redirects, so a page's path is its
permanent
+URL. Do not rename or move a published page: it breaks every existing link to
it.
+
+## Documenting the broker
+
+Much of the documentation describes behaviour that is defined in
+[apache/iggy](https://github.com/apache/iggy): configuration keys, CLI
+arguments, SDK signatures and defaults. Nothing in this repository is generated
+from that source, so the two can drift.
+
+When correcting such a page, please verify the claim against the broker's
+default branch and say so in the pull request. Naming the file you checked
+(for example `core/server/config.toml`, or the SDK source for a client method)
+is enough. A documented default that no longer matches the code is a bug worth
+fixing on its own.
+
+If you find that the broker's own behaviour is wrong rather than its
+documentation, file the issue on
+[apache/iggy](https://github.com/apache/iggy/issues) instead.
+
+## Publishing
+
+Pull requests merge to `main`. The published sites are built from separate
+branches:
+
+- `asf-site` → iggy.apache.org (production)
+- `asf-staging` → iggy.staged.apache.org (staging)
+
+Contributors do not need to touch either branch.
+
+## Getting help
+
+- [[email protected]](mailto:[email protected]), the project's
development
+ mailing list, for project decisions and anything that should stay on the
+ public record ([subscribe](mailto:[email protected]))
+- [Discord](https://discord.gg/apache-iggy) for informal conversation and quick
+ questions
+- [GitHub issues](https://github.com/apache/iggy-website/issues) for problems
+ with the site or its documentation
