Improve Contributing guide #1501
Conversation
|
Thanks for opening your first pull request! If you haven't yet signed our Contributor License Agreement (CLA), then please do so that we can accept your contribution. A link should appear shortly in this PR if you have not already signed one. |
| @@ -34,10 +209,6 @@ Find more information about the member role in the [community repository](https: | |||
|
|
|||
| Find more about emeritus roles in the [community repository](https://github.com/open-telemetry/community/blob/main/community-membership.md#emeritus-maintainerapprovertriager) | |||
|
|
|||
| ## Communication | |||
There was a problem hiding this comment.
Is there a reason for this to not be mentioned?
There was a problem hiding this comment.
It is mentioned actually in the guide, see under "Further Help" and the last information in the doc. @brettmc
| - Link relevant issues in the PR description. | ||
|
|
||
|
|
||
| ## Local Run/Build |
There was a problem hiding this comment.
Hi
I did my first work on this repo a few days ago, and the makefile doesn't work straight after a clone because of this line
include .env
I see what it does now, but some guidance on how to provision one would have been helpful
There was a problem hiding this comment.
How to set up .env is at the very top of DEVELOPMENT.md
There was a problem hiding this comment.
Oh bloody hell. I did look for something like development.md, totally missed the link in the main readme and then wondered why contributing.md was so slim. My fault 🤠
| - Fork the repository and create a new branch. | ||
| - Follow the coding guidelines before submitting your PR. | ||
| - Ensure tests pass locally before pushing. | ||
| - Link relevant issues in the PR description. |
There was a problem hiding this comment.
Does each PR require an issue? I have a trivial PR and will make an issue for it, but it'd be good if there were guidance in case there are some circumstances one isn't required
There was a problem hiding this comment.
I'm a contributor myself, so I guess the maintainers would have better knowledge to give a response to this
There was a problem hiding this comment.
I'm happy to receive PRs without a corresponding issue, provided the PR provides some detail.
There was a problem hiding this comment.
I'm the same as @brettmc. Although there's a risk that contributors spend more time on a PR that would not have been necessary with some up-front discussion in an issue/other channel.
| ### Branch Naming Convention | ||
| - **Feature branches**: `feature/<short-description>` | ||
| - **Bugfix branches**: `fix/<short-description>` | ||
| - **Documentation updates**: `docs/<short-description>` | ||
|
|
||
| ### Commit Message Format | ||
| - Use descriptive commit messages (e.g., `fix(tracing): resolve issue with span context`) | ||
| - Follow [Conventional Commits](https://www.conventionalcommits.org/) where possible. |
There was a problem hiding this comment.
We don't currently have a standard or practise for branch naming or commit messages. I assume this has come from another repository? Is it considered best-practise for all OpenTelemetry projects?
There was a problem hiding this comment.
Not sure if there any general format though, it can be removed if there is no standard yet for this repo though, or can be adopted this depending on what is tenable
|
A lot of this seems to be duplicate info from DEVELOPMENT.md - I don't mind which is the source of truth, but I would prefer there was just one version of the truth. Since you're aligning multiple SIGs contribution guides, maybe removing double-ups from development guide? |
About this, I asked during SIG call attended and the idea was, having information that is relevant to a contributor not a user in the contributing guide was necessary, and apparently most of that info is already in the development guide. Maybe it can be removed from the development guide instead? |
I think so - both DEVELOPMENT and CONTRIBUTING seem to serve the same purpose, so how about CONTRIBUTING completely replaces DEVELOPMENT, and remove the latter? |
That can work, so are you removing it? |
This is your PR, you're doing it :) |
The CONTRIBUTING file already has major info from the DEVELOPMENT to create this PR though, so would it be better to just take current info as is and edit into the DEVELOPMENT guide and rename? |
I think that's the same thing. End result: DEVELOPMENT no longer exists, CONTRIBUTING contains all useful info from DEVELOPMENT and is in the format you want. |
This PR is part of Add Contributing guide to repos
This update aims to make it easier for contributors to get started with the project and follow best practices while contributing while following a consistent pattern for a setup guide across the Otel ecosystem.
Certain info was taken from the DEVELOPMENT.md guide to create this
Please review and let me know if you have any suggestions or feedback.