Reshaping Contributing docs #67785

juanbuis · 2024-12-10T10:24:05Z

Adding new docs on how to contribute to WPDS, including an overview, how to get started with contributing, and specific guidance for documentation and components.

Related issue: #66016

What?

New section: Contributing
New page: Contributing/Overview
New page: Contributing/Get Ready to Contribute
New page: Contributing/Documentation
New page: Contributing/Components

Why?

Make it easier for anyone to get started contributing to the design system.

How?

Rewritten pages with clearer structure, an overview page, a new page that explains contributing to documentation, various step-by-step guides, a "how to get started" guide, plus a new "Contributing" section that holds it all.

Testing Instructions

Please check for inaccuracies, missing content, language.
Also I'd love for someone to check if i edited storybook/preview.js correctly

Adding new docs on how to contribute to WPDS, including specific guidance for documentation and components

github-actions · 2024-12-10T10:24:18Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: juanbuis <juanbuis@git.wordpress.org>
Co-authored-by: auareyou <auareyou@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: kristastevens <kristastevens@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2024-12-10T10:24:37Z

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

Type-related labels to choose from: [Type] Automated Testing, [Type] Breaking Change, [Type] Bug, [Type] Build Tooling, [Type] Code Quality, [Type] Copy, [Type] Developer Documentation, [Type] Enhancement, [Type] Experimental, [Type] Feature, [Type] New API, [Type] Task, [Type] Technical Prototype, [Type] Performance, [Type] Project Management, [Type] Regression, [Type] Security, [Type] WP Core Ticket, Backport from WordPress Core, Gutenberg Plugin.
Labels found: Needs Testing, Needs Copy Review, Design System.

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

github-actions · 2024-12-10T10:24:39Z

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @juanbuis! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

juanbuis · 2024-12-10T10:27:17Z

This is my first PR at WordPress, so apologies if I'm doing anything wrong — I'm open to any feedback! :)

kristastevens · 2024-12-10T14:28:25Z

Hi @juanbuis 👋 I'm answering the "Needs Copy Review" ping. Can you point me to the copy you'd like reviewed?

juanbuis · 2024-12-10T16:26:55Z

Hi @juanbuis 👋 I'm answering the "Needs Copy Review" ping. Can you point me to the copy you'd like reviewed?

Thank you! Would love a read-through of all new pages that have been added with this PR:

storybook/stories/contributing/contributing-components.txt
storybook/stories/contributing/contributing-documentation.txt
storybook/stories/contributing/contributing-get-ready.txt
storybook/stories/contributing/contributing-overview.txt

auareyou

Hey @juanbuis, this is looking great—I added what looks like a lot of comments but they're basically the same 2 to 3 concerns repeated across instances to make sure we address it all.

Thank you for your work! 🙏

storybook/stories/contributing/contributing-components.txt

auareyou · 2024-12-10T15:06:44Z

storybook/stories/contributing/contributing-components.txt

+- How much effort will be required to create and maintain it?  
+- Is there a clear purpose for it?  


These questions are great. I think they might have even more impact if instead of a deterrent, they could be part of a quality assurance checklist that or something of sorts?

auareyou · 2024-12-10T15:44:36Z

storybook/stories/contributing/contributing-components.txt

+- Does it overlap functionally or visually with any existing components? Can we use existing components to implement an alternative solution?  
+- How much effort will be required to create and maintain it?  
+- Is there a clear purpose for it?  
+- Can we introduce this change without causing breaking changes? Will we be able to keep this change and iterate on it in the future without causing future breaking changes?


Is this a breaking change? And maybe link to what makes a breaking change?

I can't find WordPress guidance on what makes a breaking change — do you think I could link out to general guidance?

Alternatively, we could rewrite to something like:

“Can we make this change without causing a breaking change (something that forces users to update their setup or workflows to keep things working) and will it allow future updates without similar issues?”

This is a good description:

"Breaking Changes" - A backwards-incompatible change which requires specific attention of the impacted developers to reconcile

There's also a relevant section here.

storybook/stories/contributing/contributing-components.txt

storybook/stories/contributing/contributing-get-ready.txt

storybook/stories/contributing/contributing-overview.txt

Co-authored-by: Au <auareyou@github.com>

kristastevens · 2024-12-11T14:05:57Z

Just to recap my conversation with @juanbuis—my understanding is that this text has already been reviewed by Michael Pick.

mirka

Thank you for preparing this, Juan!

I have two high-level concerns:

It is unclear what exactly the WordPress Design System is, and how "contributing to the design system" differs from "contributing to the components package", for example. In fact I don't think we can make a clear delineation between the two since it's very intertwined right now, and there is not much practical difference in the contribution process.
I'm afraid that having a completely separate set of docs for "design system contributions" in addition to the central contributing docs, despite the processes being almost identical, will lead to unnecessary duplication/fragmentation. That increases maintenance cost for us, while adding cognitive load to our audience since they may have to read through both documents.

So to balance those two out, I'm wondering if we could:

Make this more like a single landing page, where we explain what the WordPress Design System is, tell people about the Slack channel, and then link to all the relevant contribution guides that already exist centrally.
Any gaps in the existing contributing guides should ideally be improved/added on those documents themselves. (I'm sure you noticed a bunch of gaps while preparing these!)

storybook/stories/contributing/contributing-overview.txt

mirka · 2024-12-17T22:46:01Z

storybook/stories/contributing/contributing-components.txt

+- Does it overlap functionally or visually with any existing components? Can we use existing components to implement an alternative solution?  
+- How much effort will be required to create and maintain it?  
+- Is there a clear purpose for it?  
+- Can we introduce this change without causing breaking changes? Will we be able to keep this change and iterate on it in the future without causing future breaking changes?


This is a good description:

"Breaking Changes" - A backwards-incompatible change which requires specific attention of the impacted developers to reconcile

There's also a relevant section here.

storybook/stories/contributing/contributing-components.txt

mirka · 2024-12-17T22:59:32Z

storybook/stories/contributing/contributing-components.txt

+- Include inspiration from other products (optional)  
+- Tag the [@WordPress/gutenberg-components](https://github.com/orgs/WordPress/teams/gutenberg-components) and [@WordPress/gutenberg-design](https://github.com/orgs/WordPress/teams/gutenberg-design) GitHub groups
+
+Add the “Design System” label to correctly categorize your work. Also, consider adding other labels depending on your needs, like Needs Design, Needs Copy Review, Needs Dev, or Needs Accessibility Feedback.


We could leave this out, since I don't think new contributors have privileges to add arbitrary labels anyway. More experienced contributors with privileges will label them accordingly, so new contributors mostly shouldn't have to worry about it.

I see what you mean, but wouldn't it be helpful for a new contributor to get used to labeling their issues correctly?

They literally cannot because they do not have the rights. I believe it works the same on almost all open source projects on GitHub. They gain rights when they join the Triage team or meet the criteria to join the Gutenberg team.

mirka · 2024-12-17T23:07:54Z

storybook/stories/contributing/contributing-components.txt

+
+<Meta title="Contributing/Components" />
+
+# Contribute to components


I think it would be better if we reviewed changes as a diff on the original file, since it's unclear which parts have been changed here from the original.

mirka · 2024-12-17T23:10:19Z

storybook/stories/contributing/contributing-documentation.txt

+### **Small copy changes**
+
+If you see a spelling, punctuation, or grammatical error anywhere in the documentation, you can help fix it. 


These trivial edits definitely don't need an issue opened beforehand — it can go direct to a PR.

Opening an issue is easier than creating a PR for people who aren't comfortable with Git — especially in the current workflow that requires forking and cloning the entire repo. I think having this option allows more people to contribute, but I'll rewrite everything to make it clear that if you're comfortable creating a PR, that you can just do that :)

Ideally there'd be an "edit page" button that allows someone to directly create a PR with any copy edits, but I don't think that's possible with the current setup.

It should be pretty easy to make copy edits without forking/cloning locally. Edits can go straight to PR in the browser (for example using this link).

mirka · 2024-12-17T23:17:00Z

storybook/stories/contributing/contributing-documentation.txt

+
+After opening your issue, reviewers will start a discussion in the comments to see if it's an appropriate change. When it’s approved, the community will take care of making the change — unless you want to create a PR yourself.
+
+### **Adding new pages**


I'm kind of doubting that a new contributor would be able to (or even want to) author a page from scratch on a foundational aspect of the design system, which requires a deep understanding of the whole.

I wonder if we should focus on improving flows for the more likely entry points for new contributors, which will be to edit existing pages. For example I could add some kind of footer on the doc pages, that links out to a GitHub view to edit the doc.

Co-authored-by: Lena Morita <lena@jaguchi.com>

tyxla · 2024-12-19T15:36:22Z

storybook/stories/contributing/contributing-documentation.txt

+
+Creating a new page takes more work and will need feedback from the community. That’s why you’ll need to open an issue on GitHub to track the progress of your new page.
+
+#### **Step 1: Open a GitHub issue**


I was surprised to see this document going into such depth. Before going into writing those up in such detail, I'd suggest:

Referring to any pre-existing documentation in https://github.com/WordPress/gutenberg/tree/trunk/docs (in this case, https://github.com/WordPress/gutenberg/tree/trunk/docs/contributors#repository-management and https://github.com/WordPress/gutenberg/blob/trunk/docs/contributors/repository-management.md#issues are good examples)

Linking to the respective documentation from here, keeping this mostly an index with context and links

Contributing to the existing /docs to improve them if a detail is missing

Creating new /docs if an aspect of contributing is not documented at all

After all, if a document tries to address all questions and solve all problems, it usually addresses none. And there's no need to rediscover the wheel; we are standing on the shoulders of giants when reusing the existing docs that are the product of years of iteration from many contributors.

Reshaping Contribution docs

390410a

Adding new docs on how to contribute to WPDS, including specific guidance for documentation and components

juanbuis added the Design System Issues related to the system of combining components according to best practices. label Dec 10, 2024

github-actions bot added the First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository label Dec 10, 2024

juanbuis added Needs Testing Needs further testing to be confirmed. Needs Copy Review Needs review of user-facing copy (language, phrasing) and removed First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository labels Dec 10, 2024

juanbuis requested review from mirka and cli-automattic December 10, 2024 10:26

juanbuis self-assigned this Dec 10, 2024

juanbuis requested a review from auareyou December 10, 2024 14:02

Removing internal links + references

6be51d6

Removing references

fbc71cc

auareyou reviewed Dec 10, 2024

View reviewed changes

juanbuis and others added 7 commits December 11, 2024 10:10

Update storybook/stories/contributing/contributing-components.txt

29e18ec

Co-authored-by: Au <auareyou@github.com>

Update storybook/stories/contributing/contributing-components.txt

29effbe

Co-authored-by: Au <auareyou@github.com>

Tiny copy change

5e1f238

Merge branch 'trunk' of https://github.com/juanbuis/gutenberg into trunk

7e26bb5

Apply copy suggestions

7b09e72

Co-authored-by: Au <auareyou@github.com>

Small copy changes

847a7d2

Update contributing-components.txt

05f2f75

mirka reviewed Dec 17, 2024

View reviewed changes

juanbuis and others added 2 commits December 19, 2024 11:28

Update storybook/stories/contributing/contributing-overview.txt

54006bf

Co-authored-by: Lena Morita <lena@jaguchi.com>

Update storybook/stories/contributing/contributing-components.txt

01d1682

Co-authored-by: Lena Morita <lena@jaguchi.com>

juanbuis added 2 commits December 19, 2024 12:09

Update contributing-components.txt

6df6c52

Merge branch 'trunk' of https://github.com/juanbuis/gutenberg into trunk

d80d386

tyxla reviewed Dec 19, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reshaping Contributing docs #67785

Reshaping Contributing docs #67785

juanbuis commented Dec 10, 2024 •

edited

Loading

github-actions bot commented Dec 10, 2024 •

edited

Loading

github-actions bot commented Dec 10, 2024 •

edited

Loading

github-actions bot commented Dec 10, 2024

juanbuis commented Dec 10, 2024 •

edited

Loading

kristastevens commented Dec 10, 2024

juanbuis commented Dec 10, 2024 •

edited

Loading

auareyou left a comment

auareyou Dec 10, 2024

auareyou Dec 10, 2024

juanbuis Dec 11, 2024

mirka Dec 17, 2024

kristastevens commented Dec 11, 2024

mirka left a comment

mirka Dec 17, 2024

mirka Dec 17, 2024

juanbuis Dec 19, 2024

mirka Dec 19, 2024

mirka Dec 17, 2024

mirka Dec 17, 2024

juanbuis Dec 19, 2024

mirka Dec 19, 2024

mirka Dec 17, 2024

tyxla Dec 19, 2024

		- How much effort will be required to create and maintain it?
		- Is there a clear purpose for it?


		<Meta title="Contributing/Components" />

		# Contribute to components

		### Small copy changes

		If you see a spelling, punctuation, or grammatical error anywhere in the documentation, you can help fix it.


		After opening your issue, reviewers will start a discussion in the comments to see if it's an appropriate change. When it’s approved, the community will take care of making the change — unless you want to create a PR yourself.

		### Adding new pages


		Creating a new page takes more work and will need feedback from the community. That’s why you’ll need to open an issue on GitHub to track the progress of your new page.

		#### Step 1: Open a GitHub issue

Reshaping Contributing docs #67785

Are you sure you want to change the base?

Reshaping Contributing docs #67785

Conversation

juanbuis commented Dec 10, 2024 • edited Loading

What?

Why?

How?

Testing Instructions

github-actions bot commented Dec 10, 2024 • edited Loading

github-actions bot commented Dec 10, 2024 • edited Loading

github-actions bot commented Dec 10, 2024

juanbuis commented Dec 10, 2024 • edited Loading

kristastevens commented Dec 10, 2024

juanbuis commented Dec 10, 2024 • edited Loading

auareyou left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kristastevens commented Dec 11, 2024

mirka left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

juanbuis commented Dec 10, 2024 •

edited

Loading

github-actions bot commented Dec 10, 2024 •

edited

Loading

github-actions bot commented Dec 10, 2024 •

edited

Loading

juanbuis commented Dec 10, 2024 •

edited

Loading

juanbuis commented Dec 10, 2024 •

edited

Loading