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
content/en/governance.md
Outdated
| - handling code-of-conduct issues | ||
|
|
||
| This committee is effectively the technical and community governance body of the OpenMS project. | ||
| ### Core Developers |
There was a problem hiding this comment.
There seems to be some redundancies.
There was a problem hiding this comment.
Can you clarify which?
There was a problem hiding this comment.
Basically all ;) roles of devs etc
content/en/onboarding.md
Outdated
|
|
||
| --- | ||
|
|
||
| # Infrastructure Overview |
There was a problem hiding this comment.
I personally prefer such information in the dedicated Md files in the GitHub repository. Not on a web page.
There was a problem hiding this comment.
Thats fair. My goal here is to create an organizational onboarding document, and leave the technical specifics to the developers guide in our readthedocs. I'm certainly happy to move items your think belong elsewhere out of here.
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.
content/en/governance.md
Outdated
| - handling code-of-conduct issues | ||
|
|
||
| This committee is effectively the technical and community governance body of the OpenMS project. | ||
| ### Core Developers |
There was a problem hiding this comment.
Can you clarify which?
content/en/onboarding.md
Outdated
|
|
||
| --- | ||
|
|
||
| # Infrastructure Overview |
There was a problem hiding this comment.
Thats fair. My goal here is to create an organizational onboarding document, and leave the technical specifics to the developers guide in our readthedocs. I'm certainly happy to move items your think belong elsewhere out of here.
content/en/onboarding.md
Outdated
| # Next Steps | ||
|
|
||
| To continue exploring the project, you may want to: | ||
|
|
||
| - read the developer documentation | ||
| - explore the OpenMS repositories | ||
| - review open issues | ||
| - submit your first pull request |
There was a problem hiding this comment.
honestly not sure how helpful this is...
if we want to keep it then we should provide links here
content/en/onboarding.md
Outdated
| You can: | ||
|
|
||
| - open an issue with your question | ||
| - comment on an existing issue | ||
| - ask for clarification during pull request discussions |
There was a problem hiding this comment.
seems a bit odd and random...
content/en/onboarding.md
Outdated
| If you would like to contribute but are unsure where to start, there are many possible ways to get involved. | ||
|
|
||
| Examples include: | ||
|
|
||
| - improving documentation | ||
| - fixing bugs | ||
| - adding tests | ||
| - improving build infrastructure | ||
| - implementing new algorithms | ||
|
|
||
| Issues labeled **"good first issue"** are often a good place for new contributors to begin. | ||
|
|
||
| If you are unsure where to start, feel free to ask for suggestions in the issue tracker. |
There was a problem hiding this comment.
not sure how helpful this bulletpoint list is for a newcomer...
There was a problem hiding this comment.
I think having a really basic, here's how you can help is necessary. I'm happy to revise it if you have specific suggestions.
content/en/onboarding.md
Outdated
| Key components include: | ||
|
|
||
| - the main OpenMS C++ codebase | ||
| - pyOpenMS Python bindings | ||
| - documentation hosted on ReadTheDocs | ||
| - continuous integration systems that automatically test contributions |
There was a problem hiding this comment.
I find these kind of bullet points not super useful (also I would not call them components). In principle listing the repositories and what they are good for in our organization provides most information without going to much into detail.
| If you encounter a bug or have an idea for an improvement, open a GitHub issue describing: | ||
|
|
||
| - what problem you encountered | ||
| - steps to reproduce it (if applicable) | ||
| - possible ideas for improvement |
There was a problem hiding this comment.
would just add a link and there we already state what needs to be provided
There was a problem hiding this comment.
The problem is that we don't actually say any of this in the developer documentation. We have a link to http://nvie.com/posts/a-successful-git-branching-model/ but that's way to much for someone who just wants something simple. We should have a very simple description of the workflow somewhere, and I'd argue that here is appropriate, as more advanced folks will have already clicked on the developer guidelines linked above.
There was a problem hiding this comment.
https://github.com/OpenMS/OpenMS/tree/develop/.github/ISSUE_TEMPLATE we are pretty explicit on what to provide
There was a problem hiding this comment.
But that's not documentation. The user needs to have already decided that they want to file a bug report (and know how and where to do that). The Onboarding target is metaphorically the alien who has landed on planet earth, knows english, and that they want to help OpenMS, but nothing else.
There was a problem hiding this comment.
Sounds hyper inclusive ;)
Guess doesn’t hurt… so please go ahead
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.
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
content/en/onboarding.md
Outdated
| - [Governance](./governance.md) | ||
| - [Executive Committee](./exec_committee.md) | ||
| - [Core Developers](./core_developers.md) |
There was a problem hiding this comment.
Missing bidirectional navigation links.
This onboarding page links to governance-related pages, but those pages don't link back to the onboarding guide. Additionally, content/en/contribute.md (a natural entry point for new contributors) doesn't reference this comprehensive onboarding page.
Impact: New contributors may never discover this onboarding guide, defeating its purpose as a central resource.
Evidence from codebase:
content/en/governance.md(lines 1-9): Lists related pages but not onboardingcontent/en/exec_committee.md(lines 1-9): No reference to onboardingcontent/en/core_developers.md(lines 1-9): No reference to onboardingcontent/en/contribute.md(lines 1-25): Primary contributor entry point, but no onboarding link
Would you like me to suggest specific text additions for each of these pages to create proper bidirectional navigation?
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@content/en/onboarding.md` around lines 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.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check link formats in other markdown files to establish the convention
rg -n '\]\(' content/en/*.md | head -20Repository: OpenMS/OpenMS-website
Length of output: 7953
🏁 Script executed:
# First, let's see the actual content at lines 35-37 in onboarding.md
sed -n '30,40p' content/en/onboarding.mdRepository: OpenMS/OpenMS-website
Length of output: 399
🏁 Script executed:
# Search for all relative link patterns (./filename.md) across markdown files
rg '\]\(\./' content/en/*.mdRepository: OpenMS/OpenMS-website
Length of output: 382
🏁 Script executed:
# Also check for all internal link patterns to understand the convention
rg '\]\(/' content/en/*.md | head -30Repository: OpenMS/OpenMS-website
Length of output: 3185
Fix internal link format to match site convention.
The links on lines 35-37 use relative paths (./governance.md, ./exec_committee.md, ./core_developers.md), while all other markdown files across the site use absolute paths with a leading slash (e.g., /governance, /exec_committee). This inconsistency is also present on line 192. Update these links to use the site-wide absolute path format.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@content/en/onboarding.md` around lines 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.
|
|
||
| For **informal discussions and quick questions**, the OpenMS community also maintains a Discord server: | ||
|
|
||
| https://discord.gg/v9tv5BxPch |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Find all Discord invite links to verify which is the canonical one
rg -n 'discord\.gg' content/Repository: OpenMS/OpenMS-website
Length of output: 678
Multiple Discord invite URLs must be unified across the site.
The codebase currently references three different Discord invite URLs, which will confuse users and split the community:
https://discord.gg/v9tv5BxPch(onboarding.md:80)https://discord.gg/aJyWqf6uCn(contribute.md:18, communication.md:24)https://discord.gg/4TAGhqJ7s5(communication.md:16)
Identify the canonical Discord invite URL and update all references to use it consistently.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@content/en/onboarding.md` at 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.
2 participants
Add description of the interplay between OpenMS inc and the executive Committee.
Summary by CodeRabbit
New Features
Documentation