Conversation
✅ Deploy Preview for openms ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds governance and onboarding documentation (Core Developers, Executive Committee, Governance, Onboarding), updates site navigation and footer links to point to these pages, and updates the contributors page link to reference the Executive Committee. Changes
Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@content/governance.md`:
- Line 105: The heading "## 7. Relationship Between OpenMS Inc. and the OpenMS
Executive Committee" includes a stray "7." that should be removed to match other
unnumbered peer sections; update the heading text (the Markdown heading for
"Relationship Between OpenMS Inc. and the OpenMS Executive Committee") to "##
Relationship Between OpenMS Inc. and the OpenMS Executive Committee" so the
document and TOC render consistently.
- Around line 1-127: The governance page file must be relocated so the site
generator finds it: move the markdown currently at content/governance.md into
content/en/governance.md (matching the languages.en.contentDir setting in
config.yaml); after moving, verify any internal relative links or navigation
entries pointing to /governance still resolve and update them if necessary.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 823486d8-8ce7-487f-88ee-8e7ae18bc124
📒 Files selected for processing (2)
config.yamlcontent/governance.md
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
content/en/contributors.md (1)
14-14: Use descriptive link text instead of “here”.This reads fine, but generic anchor text is harder to scan and less accessible. Something like “see the [Executive Committee page]” would be clearer.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/en/contributors.md` at line 14, Replace the non-descriptive anchor text "[here]({{< relref \"/exec_committee\" >}})" with a descriptive label such as "[Executive Committee page]({{< relref \"/exec_committee\" >}})" (or "[Executive Committee]") so the link text clearly identifies the target; update the line containing the relref reference accordingly to improve clarity and accessibility.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@config.yaml`:
- Around line 157-158: The footer link "link: /core-developers" points to a URL
that doesn't match the new page filename core_developers; either add slug:
core-developers to the front matter of content/en/core_developers.md so Hugo
publishes it at /core-developers, or change the footer entry in config.yaml from
link: /core-developers to link: /core_developers so it matches the generated
URL; update whichever file you choose (the front matter in
content/en/core_developers.md or the footer block in config.yaml) and ensure
governance.md links remain consistent.
In `@content/en/exec_committee.md`:
- Around line 47-50: The phrase "by request of the member themself" under the
"Removal of Core Developers" heading reads awkwardly; replace "themself" with a
grammatically correct alternative such as "themselves" or simplify to "by
request of the member" so the sentence reads e.g. "or by request of the member
themselves" (or "or by request of the member") to improve clarity and tone.
---
Nitpick comments:
In `@content/en/contributors.md`:
- Line 14: Replace the non-descriptive anchor text "[here]({{< relref
\"/exec_committee\" >}})" with a descriptive label such as "[Executive Committee
page]({{< relref \"/exec_committee\" >}})" (or "[Executive Committee]") so the
link text clearly identifies the target; update the line containing the relref
reference accordingly to improve clarity and accessibility.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 9d4c0393-4692-4a65-bd16-4b33e5ea7539
📒 Files selected for processing (5)
config.yamlcontent/en/contributors.mdcontent/en/core_developers.mdcontent/en/exec_committee.mdcontent/en/governance.md
There was a problem hiding this comment.
🧹 Nitpick comments (1)
content/en/onboarding.md (1)
55-55: Heading level skips from h1 to h3.Under the
# Communicationsection (line 49), subsections like### GitHub Issuesjump directly to h3, skipping h2. The same pattern occurs at line 104 under# Development Workflow. For proper semantic structure and accessibility, consider using##for these subsections.📝 Suggested fix for heading hierarchy
-### GitHub Issues +## GitHub IssuesApply the same change to
### GitHub Pull Requests,### Discord,### Project Meetings,### Reporting Issues,### Submitting Changes, and### Code Review.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/en/onboarding.md` at line 55, Several section headings under "# Communication" and "# Development Workflow" use "###" (h3) and skip h2; change those to "##" to restore proper heading hierarchy: update the headings titled "GitHub Issues", "GitHub Pull Requests", "Discord", "Project Meetings", "Reporting Issues", "Submitting Changes", and "Code Review" from "###" to "##" so they sit directly under their parent H1 sections and maintain semantic structure and accessibility.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@content/en/onboarding.md`:
- Line 55: Several section headings under "# Communication" and "# Development
Workflow" use "###" (h3) and skip h2; change those to "##" to restore proper
heading hierarchy: update the headings titled "GitHub Issues", "GitHub Pull
Requests", "Discord", "Project Meetings", "Reporting Issues", "Submitting
Changes", and "Code Review" from "###" to "##" so they sit directly under their
parent H1 sections and maintain semantic structure and accessibility.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: f57a719f-3c73-4cbc-8916-eb5d2127b396
📒 Files selected for processing (3)
config.yamlcontent/en/exec_committee.mdcontent/en/onboarding.md
timosachsenberg
left a comment
timosachsenberg
left a comment
There was a problem hiding this comment.
I think contributing.md, architecture.md etc. Are more convenient and standard for modern projects. For discussion
poshul
left a comment
poshul
left a comment
There was a problem hiding this comment.
I'm happy to discuss. I think the pages on governance, and the relationship between the project and the nonprofit are very important for us to have somewhere.
timosachsenberg
left a comment
timosachsenberg
left a comment
There was a problem hiding this comment.
Review
Issues Found
1. Critical: Broken relative links in onboarding.md
Lines 39-41 and line 208 use bare Markdown relative links:
- [Governance](./governance.md)
- [Executive Committee](./exec_committee.md)
- [Core Developers](./core_developers.md)This is a Hugo site. These ./file.md links will not resolve in the built site. They should use Hugo's relref shortcode (as contributors.md does) or absolute paths:
- [Governance]({{< relref "/governance" >}})2. Critical: No Hugo front matter on any new page
All four new files (core_developers.md, exec_committee.md, governance.md, onboarding.md) lack front matter entirely. Existing pages like contributors.md have front matter with title, layout, etc. Depending on the theme, this may cause rendering issues, missing page titles in <head>, or problems with Hugo's page bundle system. At minimum, each file should have:
---
title: "Governance"
---(The Netlify deploy preview appears to work, so the theme may be tolerant of this, but it's still non-standard and fragile.)
3. Major: Significant content redundancy (also flagged by @timosachsenberg)
governance.md repeats nearly all the substance of exec_committee.md and core_developers.md:
| Topic | governance.md | exec_committee.md | core_developers.md |
|---|---|---|---|
| Core developer roles | ✅ | ✅ | ✅ |
| Adding core devs (majority vote) | ✅ | ✅ | ✅ |
| Removing core devs (2/3 vote) | ✅ | ✅ | ✅ |
| Executive Chairperson details | ✅ | ✅ | ❌ |
| Meeting requirements | ✅ | ✅ | ❌ |
| Transparency / minutes | ✅ | ✅ | ✅ |
governance.md was intended as an overview page linking to the detailed pages (it says so in its opening lines), but then proceeds to duplicate all the details. Recommendation: Strip governance.md down to a true overview with brief summaries and links, or consolidate everything into a single page.
4. Minor: Missing trailing newlines
All four new files end without a trailing newline (\ No newline at end of file in the diff). Standard practice is to include one.
5. Minor: Heading hierarchy in onboarding.md
Multiple sections jump from # (h1) directly to ### (h3), skipping ##:
# Communication ← h1
### GitHub Issues ← h3 (should be ## or the parent should be ##)This affects semantic structure and accessibility. Either demote the parent headings to ## or promote the subsections to ##.
6. Minor: Leading blank line in governance.md
The file starts with a blank line before the # Governance Structure of OpenMS heading (line 1 is empty).
7. Minor: Missing blank line before heading in governance.md
Around line 72, there's no blank line separating the paragraph from the next heading:
This committee is effectively the technical and community governance body of the OpenMS project.
### Core Developers8. Minor: contributors.md — non-descriptive link text
please see [here]({{< relref "/exec_committee" >}})"here" is poor link text for accessibility. Better: see the [Executive Committee page](...).
9. Minor: "Current Core Developers" is a placeholder
core_developers.md has a "Coming soon" section. This should either be populated before merge or tracked as a follow-up issue.
10. Cosmetic: onboarding.md contributor path formatting
Lines 200-204 use plain text for the progression:
User
→ Contributor
→ Frequent contributor
→ Core developer
This would look better as a proper list or styled block.
Navigation changes (config.yaml)
- Footer column2: Reordered "Contribute" / "Code of conduct"; added "Core Developers" — looks fine.
- Footer column3: Replaced old "Help" link with "Executive committee" and "Governance" — good.
- Footer column4: "Help" moved here — fine.
- Navbar "About Us": "OpenMS Inc." (→
/about) replaced with "Governance" (→/governance). The/aboutpage still exists and is linked from footer and withingovernance.md, so it remains reachable.
Summary
The PR adds valuable governance documentation, but has technical issues (broken Hugo links, missing front matter) that should be fixed, a structural problem (heavy content redundancy across 3 pages), and an open design discussion about where onboarding content belongs. I'd recommend addressing items 1–3 before merging.
content/en/onboarding.md
Outdated
There was a problem hiding this comment.
I would just put one or two sentenced and link to https://github.com/OpenMS/OpenMS/blob/develop/CONTRIBUTING.md (which also needs some love)
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (1)
content/en/onboarding.md (1)
1-206: Consider referencing the Code of Conduct.The
content/en/contribute.mdpage prominently mentions the Code of Conduct as part of welcoming new contributors: "We have a Code of Conduct to foster an open and welcoming environment." Since this onboarding guide is also intended for new contributors, consider adding a similar reference to set community expectations and values.📜 Suggested addition
Add to the "Start Here" or "Communication" section:
## Community Guidelines Our community aspires to treat everyone equally and to value all contributions. We have a [Code of Conduct](/code-of-conduct) to foster an open and welcoming environment.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content/en/onboarding.md` around lines 1 - 206, The onboarding page (content/en/onboarding.md) is missing a reference to the project's Code of Conduct; add a short "Community Guidelines" note either under the "Start Here" or "Communication" section that links to /code-of-conduct and briefly states the project's expectations (e.g., "We have a Code of Conduct to foster an open and welcoming environment") so new contributors see community standards early; update the text near the "Start Here" heading or within the "Communication" subsection to include this link and brief line.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@content/en/onboarding.md`:
- Line 55: The "GitHub Issues" and other subsection headings under the top-level
"Communication" heading use h3 (###) but should be h2 (##) to preserve proper
heading hierarchy; update the headings titled "GitHub Issues" and the other
subsection headings referenced at lines 66, 76, and 91 by changing their leading
### to ## so they sit directly under the main "Communication" section.
- Around line 35-37: Add a reciprocal link to the onboarding guide from each
governance-related page and add an onboarding pointer in the main contributor
entry: update content/en/governance.md, content/en/exec_committee.md, and
content/en/core_developers.md to include a “See also: Onboarding” (or similar)
link pointing to content/en/onboarding.md, and update content/en/contribute.md
to include a prominent link or callout to content/en/onboarding.md so new
contributors can easily discover the comprehensive onboarding guide.
- Around line 35-37: Replace the three relative links "./governance.md",
"./exec_committee.md", and "./core_developers.md" with the site-wide absolute
paths "/governance", "/exec_committee", and "/core_developers" respectively
(these appear in the current diff block), and also update the same relative-link
occurrence later in the file (reported around line 192) to the corresponding
absolute path format so all onboarding links follow the site convention.
- Line 104: The headings under the Development Workflow section use h3 (###)
directly under the h1—change the section-level headings to h2 (##) to fix the
hierarchy: locate the heading with text "Reporting Issues" and the other two
subsection headings in that same Development Workflow block (the ones currently
formatted as ###) and replace their leading "###" with "##" so they sit as
proper h2 subsections.
- Line 173: Update the sentence "If you are unsure where to start, feel free to
ask for suggestions in our discord server, or send us an email." to either
include the actual contact channels or link to the existing Contribute page;
specifically replace or augment that line in content/en/onboarding.md with a
direct email address or a link to content/en/contribute.md (or the mailing list
subscription URLs shown there) and ensure the Discord link matches the canonical
Discord URL used elsewhere.
- Line 80: There are three different Discord invite URLs in the docs
(https://discord.gg/v9tv5BxPch, https://discord.gg/aJyWqf6uCn,
https://discord.gg/4TAGhqJ7s5); pick the canonical invite URL (confirm with
product/owner) and replace every instance of the other two with that canonical
URL across the repo, specifically updating the occurrences in onboarding.md
(current v9tv5BxPch), contribute.md (aJyWqf6uCn), and communication.md
(aJyWqf6uCn and 4TAGhqJ7s5) so all docs link to the single agreed invite. Ensure
links in Markdown and any plain-text references are changed and run a
grep/search to verify no remaining old invites remain.
---
Nitpick comments:
In `@content/en/onboarding.md`:
- Around line 1-206: The onboarding page (content/en/onboarding.md) is missing a
reference to the project's Code of Conduct; add a short "Community Guidelines"
note either under the "Start Here" or "Communication" section that links to
/code-of-conduct and briefly states the project's expectations (e.g., "We have a
Code of Conduct to foster an open and welcoming environment") so new
contributors see community standards early; update the text near the "Start
Here" heading or within the "Communication" subsection to include this link and
brief line.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: f3d0959c-b64e-4684-b495-ef0faab68bc3
📒 Files selected for processing (1)
content/en/onboarding.md
|
@timosachsenberg I've aligned this and the other two places we have developer-ish documentation, and made sure that there are links between them. |
|
builds fail |
just fixed it. |
|
please consolidate menu entries |
2 participants
Add description of the interplay between OpenMS inc and the executive Committee.
Summary by CodeRabbit
New Features
Documentation