DOC: Move bug reports and feature requests to top of contributing index #28011
Conversation
|
Um so it's in contribute b/c we say in the "other ways to contribute" section that filing bug reports and feature requests are ways to contribute. Which putting it as a subsection of that might make more sense - or on the triage page. I'm very wary about adding specific content to the index pages b/c I think that's how they start to grow "oh and also what about this" ETA: I'm kinda net-neutral in that I'm concerned about organization but also understand this as a short cut. |
I first thought to extract the two sections to a different page. But since I wanted a tiny bit of context directly in the card (not only a bare button "Create a pull request"), the card more or less duplicated the sections on the separate page. In case we'd want more information in the future, we are free to add that page. Also from a conceptual point, we should not have too much specific information on issue and PR creation in the docs. Not everybody comes through the docs. Thus, it is better if relevant information is in the PR template, so that everybody gets it. I therefore find it justified to take the shortcut here. |
There was a problem hiding this comment.
So this might be better for a follow up issue, but in line w/ why I think that paragraph should stay up top, I think this paragraph should get moved to right under the "new contributors" heading
If you are new to contributing, we recommend that you first read our contributing guide. If you are contributing code or documentation, please follow our guides for setting up and managing a development environment and workflow. For code, documentation, or triage, please follow the corresponding contribution guidelines.
doc/devel/index.rst
Outdated
| We also welcome you to get more involved with the Matplotlib project. | ||
| There are various ways to contribute: | ||
| optimizing and refactoring code, detailing unclear documentation and writing new | ||
| examples, reporting and fixing bugs and requesting and implementing new features, | ||
| helping the community... | ||
|
|
There was a problem hiding this comment.
I still think this should be on the top since it's the lead in/why for reading the whole page. I
| We also welcome you to get more involved with the Matplotlib project. | |
| There are various ways to contribute: | |
| optimizing and refactoring code, detailing unclear documentation and writing new | |
| examples, reporting and fixing bugs and requesting and implementing new features, | |
| helping the community... | |
| We welcome you to get more involved with the Matplotlib project. | |
| There are various ways to contribute: | |
| optimizing and refactoring code, detailing unclear documentation and writing new | |
| examples, helping the community, reporting and fixing bugs and requesting and implementing new features... |
There was a problem hiding this comment.
I was thinking in the direction of separating simple feedback in form of issues and feature requests from direct involvement in the project, because I believe people have a quite clear idea whether they want to do the one or the other.
How about adding sections
- Bug reports and feature requests
- Contributing to Matplotlib
and putting the above text in the second section?
There was a problem hiding this comment.
The preamble is explicitly saying that bugs and features are forms of contributing...like the primary reason I'm saying to put it up top is b/c otherwise we're repeating the same language anyway since landing pages need a context setting preamble anyway.
We welcome you to get more involved with the Matplotlib project.
There are various ways to contribute:
optimizing and refactoring code, detailing unclear documentation and writing new
examples, helping the community, reporting and fixing bugs and requesting and implementing new features...
There was a problem hiding this comment.
but also I get if I'm gonna just have to show what I mean in a follow on PR
There was a problem hiding this comment.
IMHO the main issue here is that "contributing" is used in two ways.
- General contribution, which is every interaction with the project (including openening an issue or feature request)
https://matplotlib.org/devdocs/devel/index.html - Getting involved with the project in the sense of actively working with the code/documentation/community.
https://matplotlib.org/devdocs/devel/contribute.html
logical: A general contribution is one of two types
- posting an issue or feature request
- actively working with the code/documentation/community
The first is more like giving a feedback with no intention of longer relationship. The second involves getting to know the project structures and is thus far more complex. I would really like to distinguish the two types, because the relevant information for the two target groups is significantly different and by clearly distinguishing between them, we can provide exactly the required information for each.
I feel we are missing a good terminology for the cases here.
There was a problem hiding this comment.
I would really like to distinguish the two types, because the relevant information for the two target groups is significantly different and by clearly distinguishing between them, we can provide exactly the required information for each.
I get what you're saying but also we're putting them on the same page so I don't think that the answer is adding another layer of hierarchy or burying the preamble. Though hmm, thinking about this more, maybe just removing this line since we literally invite folks to do it in the next two boxes may help with the flow a bit:
As a user, you can give valuable feedback by reporting bugs and suggesting features
And possibly making the border color around 'bugs + issues' different or turning the other cards into grids - making this a primarily visual distinction.
There was a problem hiding this comment.
I've removed the sentence. The bugs and features cards have a shadow and an icon in the heading. IMHO this makes them visually distinct from other cards on the page - in particular the shadow also detaches the cards from the otherwise flat content of the page. I'm a bit hesitant to play with colors too much.
There was a problem hiding this comment.
ok, I can mess around w/ the other cards in the follow up I think I'm making to tackle a couple of things.
Partially adresses matplotlib#28005. The two sections "Report a bug" and "Request a feature" were burried inside of contribute.rst. They were a bit foreign there because all other content is on direct involvement with the project, which needs much more information. To keep things focussed and directly redirect the "simple" bug report and feature request topics to GitHub, I've deleted the sections and instead created two cards at the top of devel/index.rst with essentially the content of the sections. Note that I've the list of things to include in bug reports because that's covered by our issue template on GitHub nowadays and does not need repetition here. Co-authored-by: hannah <[email protected]>
Partially adresses #28005.
The two sections "Report a bug" and "Request a feature" were burried inside of contribute.rst. They were a bit foreign there because all other content is on direct involvement with the project, which needs much more information.
To keep things focussed and directly redirect the "simple" bug report and feature request topics to GitHub, I've deleted the sections and instead created two cards at the top of devel/index.rst with essentially the content of the sections. Note that I've removed the list of things to include in bug reports because that's covered by our issue template on GitHub nowadays and does not need repetition here.