diff --git a/README.md b/README.md index 8bb7e50..d71298f 100644 --- a/README.md +++ b/README.md @@ -170,20 +170,10 @@ Normal builds use the **latest published spec release**, not the spec's `main` b ## Contributing -Pull requests are welcome. - -- Sign your commits: `git commit -s` (DCO is required) -- Use [Conventional Commits](https://www.conventionalcommits.org/) for PR titles, - for example `docs: fix typo on the model page` -- Run `make cleanup` before committing - -Come talk to us first if you're planning something large: - -- **Slack:** [#gemara](https://openssf.slack.com/archives/C09A9PP765Q) on OpenSSF Slack -- **Meetings:** every other Thursday — see the - [OpenSSF calendar](https://calendar.google.com/calendar/u/0?cid=czYzdm9lZmhwNWk5cGZsdGI1cTY3bmdwZXNAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ) - -Maintainers are listed in `_data/maintainers.yml`. +Pull requests are welcome. See the +[Contributing guide](https://gemara.openssf.org/community/contributing) on the +site for the full guidelines, including sign-off requirements and AI +attribution expectations. --- diff --git a/_data/navigation.yml b/_data/navigation.yml index d8ae16e..078c386 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -2,6 +2,13 @@ url: / - title: Community url: /community/ + children: + - title: Overview + url: /community/ + - title: Contributing + url: /community/contributing + - title: Maintainers + url: /community/maintainers - title: Roadmap url: /roadmap - title: Tutorials diff --git a/_includes/header.html b/_includes/header.html index ec473ff..a78e5a4 100644 --- a/_includes/header.html +++ b/_includes/header.html @@ -38,7 +38,18 @@

{%- for item in site.data.navigation -%} + {%- if item.children -%} +
+ {{ item.title | escape }} +
+ {%- for child in item.children -%} + {{ child.title | escape }} + {%- endfor -%} +
+
+ {%- else -%} {{ item.title | escape }} + {%- endif -%} {%- endfor -%}
diff --git a/assets/css/style.scss b/assets/css/style.scss index 22e2f28..94a7817 100644 --- a/assets/css/style.scss +++ b/assets/css/style.scss @@ -582,6 +582,44 @@ a[href^="http"]:not([href*="gemara"]):not([href*="openssf"]):not(.social-media-l } } + .nav-dropdown { + position: relative; + + summary { + cursor: pointer; + list-style: none; + + &::-webkit-details-marker { + display: none; + } + + &::after { + content: "▾"; + margin-left: var(--spacing-xs); + font-size: 0.75em; + } + } + + .nav-dropdown-menu { + display: flex; + flex-direction: column; + position: absolute; + top: 100%; + left: 0; + min-width: 160px; + padding: var(--spacing-xs); + background: var(--color-bg-primary); + border: 1px solid var(--color-border); + border-radius: var(--radius-sm); + box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); + z-index: 10; + + .page-link { + padding: var(--spacing-xs) var(--spacing-sm); + } + } + } + @media screen and (max-width: 768px) { position: relative; @@ -625,6 +663,17 @@ a[href^="http"]:not([href*="gemara"]):not([href*="openssf"]):not(.social-media-l width: 100%; padding: var(--spacing-sm) var(--spacing-md); } + + .nav-dropdown { + width: 100%; + + .nav-dropdown-menu { + position: static; + border: none; + box-shadow: none; + padding: 0 0 0 var(--spacing-md); + } + } } } diff --git a/community/contributing.md b/community/contributing.md new file mode 100644 index 0000000..79babdf --- /dev/null +++ b/community/contributing.md @@ -0,0 +1,66 @@ +--- +layout: page +title: Contributing +nav-title: Contributing +--- + +Thanks for your interest in contributing to Gemara! Contributions of all +kinds are welcome including docs, schemas, SDKs, examples, and ideas. This page +covers a few things worth knowing before you open a pull request, including +how we like AI-assisted work to be attributed. + +## Getting started + +- Sign off your commits with `git commit -s` (see [DCO](#dco) below). +- Use [Conventional Commits](https://www.conventionalcommits.org/) for PR + titles, for example `docs: fix typo on the model page`. +- Run `make cleanup` before committing to clear out generated files. + +Planning something larger? Come say hello first. We're happy to help shape +the idea: + +- **Slack:** [#gemara](https://openssf.slack.com/archives/C09A9PP765Q) on OpenSSF Slack +- **Meetings:** every other Thursday — see the [OpenSSF calendar](https://calendar.google.com/calendar/u/0?cid=czYzdm9lZmhwNWk5cGZsdGI1cTY3bmdwZXNAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ) + +## DCO + +Gemara uses the [Developer Certificate of Origin](https://developercertificate.org/), +so please sign off your commits with `git commit -s`. The sign-off says that +you wrote the change, or otherwise have the right to submit it. So it should +be yours, even when an AI tool helped you write it. + +## Working with AI + +AI-assisted contributions are welcome. We just ask that you be open about +where AI was involved, so reviewers and future maintainers understand what +they're looking at. Please refer to the Linux Foundation's [Generative AI Policy](https://www.linuxfoundation.org/legal/generative-ai) +for additional guidance. + +### Commits + +When AI helped author a commit, add an `Assisted-by:` trailer naming the tool: + +``` +Assisted-by: Claude Code +``` + +Please don't use `Co-authored-by:` for AI tools (this is blocked by our branch protections). +The DCO sign-off is a statement made by a person, so co-authorship should reflect the humans +involved. + +### PRs, issues, and comments + +If an AI generated or largely drafted a PR description, issue, or comment, +add a 🤖 so it's clear which text is AI-generated and which is yours. + +### Understanding what you contribute + +Whether a change is hand-written or AI-assisted, the goal is the same: you +should understand it well enough to walk someone through it. A good rule of +thumb is to imagine explaining the change months from now. You might not +remember every function name, but the reasoning, the design, and the +packages it relies on should still feel like yours. + +If a change gets that kind of understanding, it's in good shape. If it +doesn't yet, it's worth spending a bit more time with it before asking for a +review. diff --git a/community/index.md b/community/index.md index 2355090..1f69ba8 100644 --- a/community/index.md +++ b/community/index.md @@ -9,12 +9,8 @@ nav-title: Community - **Slack:** [#gemara](https://openssf.slack.com/archives/C09A9PP765Q) on OpenSSF Slack - **Meetings:** Bi-weekly on alternate Thursdays - see the [OpenSSF calendar](https://calendar.google.com/calendar/u/0?cid=czYzdm9lZmhwNWk5cGZsdGI1cTY3bmdwZXNAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ) - **GitHub:** [gemaraproj/gemara](https://github.com/gemaraproj/gemara) - -### Meet the Maintainers - -{% for maintainer in site.data.maintainers.maintainers %} -- {{ maintainer.name }}, {{ maintainer.organization }} (@{{ maintainer.github }}) -{% endfor %} +- **Contributing:** see the [Contributing guide](/community/contributing) +- **Maintainers:** meet the people behind Gemara on the [Maintainers page](/community/maintainers) ### Projects and Working Groups diff --git a/community/maintainers.md b/community/maintainers.md new file mode 100644 index 0000000..00b1f89 --- /dev/null +++ b/community/maintainers.md @@ -0,0 +1,16 @@ +--- +layout: page +title: Maintainers +nav-title: Maintainers +--- + +Gemara is maintained by a group of contributors across the community. These +folks review contributions, guide the project's direction, and are happy to +help you get started. + +{% for maintainer in site.data.maintainers.maintainers %} +- {{ maintainer.name }}, {{ maintainer.organization }} (@{{ maintainer.github }}) +{% endfor %} + +Want to get involved? See the [Contributing guide](/community/contributing) +or come find us on [Slack](https://openssf.slack.com/archives/C09A9PP765Q).