[TRACKING] Improve Contributing Guidelines

[vitorfloriano]

Currently, the NRC repository lacks custom guidelines for contributors, which leads to inconsistency on issues/PRs and manual toil on maintainers.

We may consider:

• Adding Issues templates/forms
• Implementing a standardized label schema (kind/ area/ priority/)
• Customizing CONTRIBUTING.md (including local setup & dev environment)
• Document available tests, add instructions for writing tests setting up ProwJobs

[edit: a few changes were deemed not necessary after discussion]
- [ ] Improving PR templates
- [ ] Standardizing commit messages (e.g., Conventional Commits)
- [ ] Adding policies for Branch naming
- [ ] Defining Merge/Squash policy for clean history

Adding guidelines/policies on how to contribute helps contributors have a clear path and facilitates automating chores like release notes, changelogs and triaging. It also makes it possible to provide contributors instant feedback through CI checks.

[Rajneesh180]

Hi, I'd like to work on this. I can see the repo has a PR template already (.github/pull_request_template.md) but no issue templates and a minimal CONTRIBUTING.md.

I'm planning to submit a focused PR that addresses:

1. GitHub issue templates — structured YAML forms for bug reports and feature requests under .github/ISSUE_TEMPLATE/, following the patterns used in other kubernetes-sigs repos
2. CONTRIBUTING.md improvements — add a local development setup section (prerequisites, how to run make test and make lint, how to set up a local cluster with kind) and a commit message conventions section (Conventional Commits as used in this repo's recent history)

Would this scope be acceptable? Happy to adjust based on maintainer preferences before opening the PR.

[Priyankasaggu11929]

Hello @vitorfloriano, thanks again for creating the issue and suggesting improvements.

• Re: Implementing a standardized label schema (kind/ area/ priority/)

  we use a tool called label_sync for adding new labels to github repos - https://github.com/kubernetes/test-infra/tree/master/label_sync

  Here's an example PR adding a bunch of labels to kubernetes/autoscaler and kubernetes-sigs/cluster-autoscaler repos - label_sync: add labels for autoscaler and cluster-autoscaler repos kubernetes/test-infra#36927

  we can start with adding a bunch of basic labels and then re-iterate with more as/when needed.

• Re: Adding policies for Branch naming

  we have a documented release process that also mentions briefly about branch naming policy for our releases branches - https://github.com/kubernetes-sigs/node-readiness-controller/blob/main/RELEASE.md

  do you think this document covers it? or we can improve it further to address gaps.

• Re: Defining Merge/Squash policy for clean history

  we're using squash strategy for this repo. It's defined here - https://github.com/kubernetes/test-infra/blob/befc6a5ebd53bbaca099ffd026b4356d29e835ca/config/prow/config.yaml#L901

• Re: Standardizing commit messages (e.g., Conventional Commits)

  Kubernetes project has some guidance documented here around commit messages (and in general for PR etiquette) - https://github.com/kubernetes/community/blob/main/contributors/guide/pull-requests.md#smaller-is-better-small-commits-small-pull-requests

  We can update the CONTRIBUTING.md guide in this repo to point there maybe

• Re: PR/Issue templates

  I would suggest let's first figure what is missing in the existing templates? like if you see something more useful in other projects that we can add here, and then we can update the templates for this repo?

• Re: Customizing CONTRIBUTING.md (including local setup & dev environment)

  So, we have this information documented here - https://github.com/kubernetes-sigs/node-readiness-controller/tree/main/docs/book/src/user-guide

  Let's maybe make it more discoverable by adding links to the root README.md file?

[vitorfloriano]

Hi @Priyankasaggu11929 thanks for the thorough response! Just a few thoughts before I take any actions:

• In regards to labels, one thing I always notice is that repos inherit a lot of labels that are not related to the project (e.g. provider-specific labels). Could we clean those up before start adding more?

• In regards to templates, we could start by adding an Issue template. Currently there's only a PR template. See: https://github.com/kubernetes-sigs/node-readiness-controller/tree/main/.github

• In regards to setting up the environment, I was thinking more of the dev environment. Just so contributors don't face issues caused by a missing tool or a wrong version, and to avoid battling the failing checks in CI because they didn't run the linter locally (I'm looking at me). Something like this: https://github.com/kubernetes-sigs/kubebuilder/blob/master/CONTRIBUTING.md .

• In regards to branch-naming, I was thinking more in something like standardizing it for contributors to allow some automations (e.g. ci/ prefixed branches will be labeled area/ci, things like that), but I guess that's not planned, so I'll deem this a case of premature optimization.

• In regards to commit messages, looking at CONTRIBUTING.md again, I think pointing contributors to the official docs is sufficient. Unless we want to ensure a certain structure to allow automation, which is not the case. I'll also deem this premature optimization.

Note

About the commit message and branch naming, looking at it again, I believe the flock of contributions that led me to think about automating some things are not usual and were caused by the mentorship program.

So, in summary, some actionable items I can see are:

1. Remove unnecessary labels, add a few fundamental ones using label_sync and iterate.
2. Create an Issue template.
3. Include dev environment setup in CONTRIBUTING.md.

WDYT?

[Priyankasaggu11929]

1. Remove unnecessary labels, add a few fundamental ones using label_sync and iterate.
2. Create an Issue template.

1,2 are good.

3. Include dev environment setup in CONTRIBUTING.md.

I still feel we should create a /contributing-guide like this user-guide and link that in the CONTRIBUTING.md

reason being - whatever we add as a contributing guide, it would be helpful to render that in NRC website.

---

Thanks for pointing to https://github.com/kubernetes-sigs/kubebuilder/blob/master/CONTRIBUTING.md.

I agree adding a list of prerequisites (if we already don't have it documented anywhere in this repo) like git, go, docker/podman, with some minimum version requirements, is good improvement
(Another suggestion - we can add a check in Makefile to ensure the required tools are available in path?)

A link pointing to NRC's prow jobs also is good addition - https://github.com/kubernetes-sigs/kubebuilder/blob/master/CONTRIBUTING.md#where-the-ci-tests-are-configured

For documentation, we have some content for mdbook related contribution here - https://github.com/kubernetes-sigs/node-readiness-controller/tree/main/docs#documentation-mdbook
so, linking that in the CONTRIBUTING.md guide would be useful too.

some information related to running (unit, e2e, integration, ...) tests locally is good as well.

For Makefile targets - I will just point to make help and ask folks to read through the output.

For AI related contribution guidelines, we can point to the overall Kubernetes project level policy - https://www.kubernetes.dev/docs/guide/pull-requests/#ai-guidance

[vitorfloriano]

Adding this here just so we keep track: #255 (comment)

[ajaysundark] Could we also document our prow workflows, how to write new tests and relevant maintenance instructions in our project? Maybe also link at the contributing guide? Not necessarily at this PR, you could create an issue and followup as you find time.