[Doc] Add a proper way to submit website issues and improvement proposals

lhotari commented 8 months ago

Search before asking

[X] I searched in the issues and found nothing similar.

What issue do you find in Pulsar docs?

The GitHub issue templates lack a way to submit website issues and improvement proposals for the website

What is your suggestion?

Just make this sensible. :) There needs to be at least labeling for website related issues. The "doc-required" label is also nonsense to me for document issues.

Any reference?

No response

Are you willing to submit a PR?

[ ] I'm willing to submit a PR!

visortelle commented 8 months ago

@lhotari I ended up with a bunch of suggestions on issue templates and labels cc @asafm

Current labels reference

``` component/config #1d76db bug The PR fixed a bug or issue reported a bug #D93F0B component/admin #1d76db component/broker #1d76db component/build #1d76db component/cli #1d76db component/client #1d76db component/compaction #1d76db component/connector #1d76db component/dependency Pull requests that update a dependency file #1d76db component/function #1d76db component/geo-replication #1d76db component/metrics #1D76DB component/proxy #1d76db component/security #1d76db component/sql Pulsar SQL related features #1d76db component/test #1d76db component/tieredstorage #1d76db component/transaction #1d76db component/websocket #1d76db doc Your PR contains doc changes, no matter whether the changes are in markdown or code files. #ffd6e5 enhancement The enhancements for the existing features or docs. e.g. reduce memory usage of the delayed messages #C2E0C6 flaky-tests #d15751 help wanted #008672 question #5319E7 release/2.4.3 #6071c1 release/2.5.1 #6071c1 release/2.5.2 #6071c1 release/2.5.3 #6071c1 release/2.6.1 #6071c1 release/2.6.2 #6071c1 type/cleanup Code or doc cleanups e.g. remove the outdated documentation or remove the code no longer in use #5319e7 type/feature The PR added a new feature or issue requested a new feature #5319e7 cherry-picked/branch-2.7 Archived: 2.7 is end of life #E48766 cherry-picked/branch-2.8 Archived: 2.8 is end of life #E48766 cherry-picked/branch-2.9 Archived: 2.9 is end of life #417B16 component/authentication #1D76DB component/ci #1D76DB component/metadata #1D76DB component/tool #1D76DB doc-complete Your PR changes impact docs and the related docs have been already added. #AF52E7 doc-label-missing #ECC6EF doc-not-needed Your PR changes do not impact docs #e0e0e0 doc-required Your PR changes impact docs and you will update later. #db115e good first issue Good for newcomers #7057ff PIP #0052cc release/2.6.3 #6071c1 release/2.6.4 #0052CC release/2.7.1 #6071c1 release/2.7.2 #6071c1 release/2.7.3 #BF6BE5 release/2.7.4 #E30DA5 release/2.7.5 #033BD0 release/2.8.1 #1d76db release/2.8.2 #BF2F60 release/2.8.3 #BC5A85 release/2.9.0 #bfdadc release/2.9.1 #58AF08 release/2.9.2 #EE2E51 release/2.9.3 #378268 release/blocker Indicate the PR or issue that should block the release until it gets resolved #D93F0B cherry-picked/branch-2.10 #0e8a16 cherry-picked/branch-2.11 #8D6765 cherry-picked/branch-3.0 #1d76db component/authorization #1d76db component/ML #1D76DB component/schema #1D76DB dependencies Pull requests that update a dependency file #0366d6 lifecycle/stale #ededed ready-to-test #0052cc release/2.10.1 #C34B56 release/2.10.2 #04B65F release/2.10.3 #90056C release/2.10.4 #7C2CAC release/2.10.5 #fbca04 release/2.10.6 #1473F9 release/2.11.0 #7CDCD2 release/2.11.1 #537E0B release/2.11.2 #0e8a16 release/2.11.3 #A3E497 release/2.7.6 #243EC0 release/2.8.4 #CC59A1 release/2.8.5 #CC59A1 release/2.9.4 #551903 release/2.9.5 #3BD887 release/3.0.1 #03282B release/3.0.2 #3FAAD0 release/important-notice The changes which are important should be mentioned in the release note #582178 Stale #ededed type/refactor Code or documentation refactors. e.g. refactor code structure or methods to improve code readability #5319E7 category/functionality Some functions are not working such as get errors #006b75 category/performance Performance issues fix or improvements #006b75 category/reliability The function does not work properly in certain specific environments or failures. e.g. data lost #006b75 cherry-picked/branch-3.1 #B968E2 cherry-picked/branch-3.2 #0052cc component/site About https://pulsar.apache.org/ #B50C64 code/go Pull requests that update Go code #16e2e2 java Pull requests that update Java code #ffa221 release/2.10.7 #fbca04 release/2.11.4 #c2e0c6 release/2.11.5 #AD7172 release/3.0.3 #F9D0C4 release/3.0.4 #c5def5 release/3.1.1 #6B378D release/3.1.2 #9FD226 release/3.1.3 #BA07CE release/3.1.4 #006B75 release/3.2.1 #E99695 release/3.2.2 #5A578B ```

Suggestions

Deprecate java label. Pulsar is written in Java and most PRs update Java code.
Instead of removing labels, deprecate them by renaming them to deprecated/<label_name>. Probably pick another prefix that is alphabetically closer to the end of the alphabet to reduce noise.
Add go label automatically using labeler: https://github.com/apache/pulsar/blob/master/.github/labeler.yml
```
go:
```
changed-files:
- any-glob-to-any-file: '*/.go'
Add component/* labels automatically based on the file path
```
component/config:
```
changed-files:
- any-glob-to-any-file: 'conf/*/'
- any-glob-to-any-file: 'pulsar-config-validation/*/' component/client:
changed-files:
- any-glob-to-any-file: 'pulsar-client/*/'
- any-glob-to-any-file: 'pulsar-client-*/*/' ...
Rename bug label to type/bug for consistency. Keep the red color.
(?) Rename component/* => area/* for shorter names. The https://github.com/kubernetes/kubernetes/labels has such naming.
Rename doc-required label to type/doc. Relabel open issues and PRs with doc labels to the type/doc.
Deprecate all other doc-* labels. If it is needed for some kind of workflow, simply use the board project with ToDo -> In Progress -> Done states.
(?) Probably it makes sense to enable and track website and docs issues in apache/pulsar-site repository. And add a good visible link to apache/pulsar README.md.
Deprecate the question label. Instead, move such issues to Discussions -> Q&A
Migrate issues with the enhancement either to type/feature label or Discussions. Add a new Suggest an idea issue template that redirects to the Discussions -> Ideas
(?) Rename PIP => type/PIP for consistency
Rename flaky-test => type/flaky-test to consistency
Deprecate lifecycle/stale label. Use Stale instead. Rename Stale => stale for consistency.
Add the ability to pick an area/* label from the dropdown on issue creation. systemd/systemd and a few other projects use this action for that: https://github.com/redhat-plumbers-in-action/advanced-issue-labeler?tab=readme-ov-file#real-life-examples

asafm commented 8 months ago

I'm very happy you guys are making this cleanup, for sure. I read it. It looks good. flacky --> flaky

The only thing I don't know, in general, is how labels are actually used, in real life.

visortelle commented 8 months ago

flacky --> flaky

thanks, good catch 👍

The only thing I don't know, in general, is how labels are used, in real life.

I can share how I see it:

We usually prioritize bugs over features. Of course with reasonable limits. Adding a label to bugs makes it easy to filter them and answer a question about what to do next.
Non-critical bugs and nice-to-have features that are planned, but not prioritized we can mark as good-first-issue and/or help-wanted to give new contributors a pool of issues they can take from.
I'm not a fan of closing stale issues that are neither resolved nor not planned. It looks like it is hiding existing problems under the sofa.
The area/* labels allow a person who is interested or has good knowledge in a specific area to filter issues related to this area to get an overview of existing problems, what is work in progress, and retrospection of what has happened in this area.

@asafm you could simply filter by area/metrics to get an overview of all the issues and PRs related to the topic you're interested in. It simplifies navigation when you have thousands of issues.

If we decide that it won't solve any Pulsar problems, no need to fix it.

If no one minds, I will apply the changes.

asafm commented 7 months ago

I don't mind. I think we need at least one person running those like @lhotari @mattisonchao @codelipenghui as they know the process quite well - I don't know it :)

lhotari commented 7 months ago

I don't mind. I think we need at least one person running those like @lhotari @mattisonchao @codelipenghui as they know the process quite well - I don't know it :)

What process is in question? The title of this issue is "Add a proper way to submit website issues and improvement proposals". The people who care about the website improvements should decide about this. I previously shared my comment on the mailing list: https://lists.apache.org/thread/0jygnbrk89cgrfnmsr6004k5w7o47fb9 .

asafm commented 7 months ago

@lhotari You are correct. I just wanted the process for website issues to be aligned with the process in general in Pulsar for triaging issues of any sort.

apache / pulsar