8000 DOC: consolidated coding guide and added naming conventions table by story645 · Pull Request #27213 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

DOC: consolidated coding guide and added naming conventions table #27213

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
Merged
timhoffm merged 1 commit into from
Nov 3, 2023
Merged

DOC: consolidated coding guide and added naming conventions table #27213

timhoffm merged 1 commit into from
Nov 3, 2023

Conversation

@story645
Copy link
Member
@story645 story645 commented Oct 27, 2023 •
edited
Loading

This started as an attempt to document variable naming conventions to address #22156 and well trying to put a table into a bullet list didn't work well and that had me thinking that a bullet list is the wrong structure when tables are involved so 😅 this PR:

  • moves a lot of text out of notes and turns it into the preambles they were functionally acting as
  • consolidates the contributor checklists sections, mostly by removing content and instead linking out to where it's discussed/described
  • better distinguish contributor content checklist from github checklist
  • move the checklist .css into the mpl.css file
  • moved info on updating a pull request to the workflow-> as with [Doc]: Move Automated Tests section to workflow docs #26998, this is to better scope the PR guidelines doc to being about the content of the PR and the git workflow doc to be about git/github specific workflow.
  • moved bulkier bullet points into coding guidelines as subsections to avoid having two coding guides b/c [Doc]: consolidate coding guidelines  #26095
  • moved all the what's new/API changes stuff out to the coding guidelines too and reworked that section a drop b/c [Doc]: consolidate coding guidelines  #26095
    • the changes to the API/What's new readmes just moves the duplicated part to the bottom so that it can get cropped in the include.
    • I would like to also remove the very large item bulleted lists here (I think most of them are really tables), but I'd like to move all the "new/changed/deprecated API" info out into its own page because it is a lot of content.

While it may not seem like it, I have tried to avoid rewording/rewriting except to remove redundancy. In particularly, I'm trying to remove duplicate sets of detailed instructions b/c I think that creates space for deviation in those instructions/confusion.

Next Steps

I think merging this should be good enough to close #26095 cause it'll at least put everything in one place (mostly). I don't want to overwhelm this PR w/ changes since it's already doing a lot more than I planned, but once this is merged I'd like to clean up the code section of the policy and guidelines page so that it can just be a TOC. To do so, I think a sensible swapping would be to

  1. move the contents of code_guidelines in contribute into the file called code guidelines
  2. move the API changes content into its own file
  3. move the pull request checklists out of coding_guidelines into their own file:
    • alt: contributor checklist -> coding guide, maintainer checklist -> pr triage file
  4. move the information that has to do with pull request triage into a pull_request_triage file and move that under triage

Basically proposing that the code section of policies & guidelines changes:

current proposed
  • coding guidelines
  • pull request guidelines
  • testing
  • coding style guide
  • API changes and new features
  • testing

and the triage section changes to

current proposed
  • bug triaging and issue curation
  • triage team
  • a typical workflow for triaging issues
  • triage team
  • bug triaging and issue curation
  • pull request triage

or the pull request triage document gets moved to maintenance, but technically I think anyone w/ triage rights can do most of the triage stuff discussed in the pull request guide.

@story645 story645 added the Documentation: devdocs files in doc/devel label Oct 27, 2023
@story645 story645 force-pushed the doc-internal branch 5 times, most recently from 87cf806 to cce1ac6 Compare October 27, 2023 16:48
story645
story645 commented Oct 27, 2023
View reviewed changes
@story645 story645 marked this pull request as draft October 30, 2023 19:41
@story645 story645 changed the title DOC: streamlined coding guide and added naming conventions table DOC: consolidated coding guide and added naming conventions table Oct 30, 2023
@story645 story645 force-pushed the doc-internal branch 3 times, most recently from f9f7f62 to 3c5e164 Compare October 30, 2023 22:48
@story645 story645 marked this pull request as ready for review October 30, 2023 22:48
@story645
Copy link
Member Author
story645 commented Oct 31, 2023

Attn @timhoffm - I moved things around so much that I figure I should check if I did anything you're opposed to.

@story645 story645 mentioned this pull request Oct 31, 2023
Open
11 tasks
@story645 story645 force-pushed the doc-internal branch 3 times, most recently from a3514c7 to 5cb6344 Compare October 31, 2023 02:47
tacaswell
tacaswell reviewed Oct 31, 2023
View reviewed changes
@story645 story645 force-pushed the doc-internal branch 3 times, most recently from 3bce52d to c5eb7a2 Compare November 1, 2023 03:13
@story645 story645 force-pushed the doc-internal branch 2 times, most recently from c0033f6 to 57f5908 Compare November 2, 2023 01:21
@timhoffm
Copy link
Member
timhoffm commented Nov 2, 2023

Attn @timhoffm - I moved things around so much that I figure I should check if I did anything you're opposed to.

Thanks for the heads up. I will check later.

@story645 story645 mentioned this pull request Nov 2, 2023
Merged
1 task
timhoffm
timhoffm reviewed Nov 2, 2023
View reviewed changes
@story645 story645 force-pushed the doc-internal branch 2 times, most recently from d690302 to e12c7db Compare November 3, 2023 04:00
@story645 @timhoffm
streamlined coding guide and added naming conventions table
5143bad 
Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
@timhoffm timhoffm merged commit 4524fdb into matplotlib:main Nov 3, 2023
@timhoffm
Copy link
Member
timhoffm commented Nov 3, 2023

@story645 please decide yourself whether you want to backport this.

@story645 story645 modified the milestones: v3.9.0, v3.8-doc Nov 3, 2023
@story645
Copy link
Member Author
story645 commented Nov 3, 2023

@meeseeksdev backport to v3.8-doc

@lumberbot-app
Copy link
lumberbot-app bot commented Nov 3, 2023

Something went wrong ... Please have a look at my logs.

It seems that the branch you are trying to backport to does not exist.

@story645
Copy link
Member Author
story645 commented Nov 3, 2023

@meeseeksdev backport to v3.8.x

@meeseeksmachine meeseeksmachine mentioned this pull request Nov 3, 2023
Merged
meeseeksmachine pushed a commit to meeseeksmachine/matplotlib that referenced this pull request Nov 3, 2023
@timhoffm @meeseeksmachine
Backport PR matplotlib#27213: DOC: consolidated coding guide and adde…
a614491 
…d naming conventions table
@story645
Copy link
Member Author
story645 commented Nov 3, 2023

@meeseeksdev backport to v3.8.1-doc

@meeseeksmachine meeseeksmachine mentioned this pull request Nov 3, 2023
Merged
meeseeksmachine pushed a commit to meeseeksmachine/matplotlib that referenced this pull request Nov 3, 2023
@timhoffm @meeseeksmachine
Backport PR matplotlib#27213: DOC: consolidated coding guide and adde…
ef107ca 
…d naming conventions table
@story645 story645 deleted the doc-internal branch November 3, 2023 13:56
@story645
Copy link
Member Author
story645 commented Nov 3, 2023

backported to avoid merge conflicts if smaller changes get backported 😓

story645 added a commit that referenced this pull request Nov 3, 2023
@story645
Merge pull request #27263 from meeseeksmachine/auto-backport-of-pr-27…
05dc36a 
…213-on-v3.8.x

Backport PR #27213 on branch v3.8.x (DOC: consolidated coding guide and added naming conventions table)
story645 added a commit that referenced this pull request Nov 3, 2023
@story645
Merge pull request #27264 from meeseeksmachine/auto-backport-of-pr-27…
c59f152 
…213-on-v3.8.1-doc

Backport PR #27213 on branch v3.8.1-doc (DOC: consolidated coding guide and added naming conventions table)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tacaswell tacaswell tacaswell left review comments

@timhoffm timhoffm timhoffm approved these changes

Assignees

No one assigned

Labels

Documentation: devdocs files in doc/devel

Projects

None yet

Milestone

v3.8-doc

Development

Successfully merging this pull request may close these issues.

[Doc]: consolidate coding guidelines

3 participants

@story645 @timhoffm @tacaswell
0