Skip to content

Single Source of truth for contributing guidelines #5246

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 7 commits into
base: rolling
Choose a base branch
from
Open

Single Source of truth for contributing guidelines #5246

wants to merge 7 commits into from

Conversation

Nils-ChristianIseke
Copy link
Contributor

@Nils-ChristianIseke Nils-ChristianIseke commented Apr 19, 2025 •
edited
Loading

We should have a single source of truth for the contributing guidelines.

@Nils-ChristianIseke
Update README.md
14fe343 
Signed-off-by: Nils-Christian Iseke <[email protected]>
@Nils-ChristianIseke Nils-ChristianIseke changed the title Update README.md Single Source of truth for contributing guidelines Apr 21, 2025
fujitatomoya
fujitatomoya reviewed Apr 21, 2025
View reviewed changes
Copy link
Collaborator

@fujitatomoya fujitatomoya left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in general, i agree with this approach to reduce the maintenance cost and redundancy. (we redeploy the documentation nightly as described here, so it would not be problem.)

there is a couple of suggestions.

kscottz
kscottz reviewed Apr 23, 2025
View reviewed changes
Copy link
Collaborator

@kscottz kscottz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am really ambivalent about this pull request but I am not going to get in the way on it getting merged. I get that we should aim for "DRY" but I also think you can take certain rules a little too far.

Is it too much to ask that less README.MD on the repo you just cloned actually contains instructions on how to build the repository? Maybe just an abridged version of the instructions?

README.md Outdated
@@ -6,67 +6,8 @@ The sources from this repository are built and uploaded to the site nightly by a
## Contributing to the documentation

Contributions to this site are most welcome.
Please see the [Contributing to ROS 2 Documentation](https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.html) page to learn more.
Please see the [Contributing to ROS 2 Documentation](https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Contributing-To-ROS-2-Documentation.html) page to learn how to contribute.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know if we necessarily want to frame this as solely contributing versus "building and contributing."

@Nils-ChristianIseke
Copy link
Contributor Author

Nils-ChristianIseke commented Apr 24, 2025 •
edited
Loading

Thank you for your review. I came across this because the documentation deviated from the instructions in the readme file. And one part of the information in the documentation was incorrect. However, I agree with you that having that information in the README is not bad. I could check if it is possible to integrate the parts of the rst into this markdown or vice versa.

@Nils-ChristianIseke
Copy link
Contributor Author

@fujitatomoya @kscottz friendly ping :).
Some alternatives I currently see:

  1. Close this PR
  2. Align the README and Contribution Guidelines (duplicate content)
  3. Remove this from the README and keep only in the Docs
  4. Remove this from the Docs and only keep it in the README
  5. Establish a single source of truth by keeping the content in one file and including it in both locations (e.g., importing .rst into .md or vice versa), though I'm uncertain about the implementation complexity.

Happy for your thoughts :)

@fujitatomoya
Copy link
Collaborator

I say keeping this PR 👍

@kscottz what do you think?

@fujitatomoya fujitatomoya requested a review from kscottz May 9, 2025 15:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@christophebedard christophebedard christophebedard approved these changes

@fujitatomoya fujitatomoya fujitatomoya approved these changes

@kscottz kscottz Awaiting requested review from kscottz

Assignees

@kscottz kscottz

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@Nils-ChristianIseke @fujitatomoya @kscottz @christophebedard