Skip to content
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.

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

Add docs contribution checklist page #10170

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

tetrapod00
Copy link
Contributor

@tetrapod00 tetrapod00 commented Oct 30, 2024

Resolves #9193.

This PR adds a new page to the Writing documentation section. It is a list of all of the content, style, and formatting guidelines that manual contributions are expected to follow. Each entry in the page concisely summarizes the guideline, then links to the section of docs that describes the guideline in full.

It is intended to be used:

  • By contributors to check their own work, in order to (hopefully) reduce the work needed during reviews.
  • By reviewers to see a summary of guidelines while reviewing. The links should make it easier to cite guidelines and link to rules when reviewing.

I kept the rules quite terse, since there are so many of them and they all link to longer versions. But I can expand them a little if it feels too terse.

If this ends up being used, possibly we will want an equivalent for engine PRs?

@tetrapod00 tetrapod00 added discussion content:new page Issues and PRs related to creation of new documentation pages for new or undocumented features area:contributing Issues and PRs related to the Contributing/Development section of the documentation labels Nov 14, 2024
@tetrapod00 tetrapod00 force-pushed the contribution-checklist branch from 5a33d67 to 2017152 Compare January 28, 2025 08:31
@tetrapod00 tetrapod00 marked this pull request as ready for review January 28, 2025 08:33
@tetrapod00 tetrapod00 changed the title [Draft] Add docs contribution checklist page Add docs contribution checklist page Jan 28, 2025
@Maarrk
Copy link
Contributor

Maarrk commented Jan 29, 2025

Do you think that an even shorter version with section links should be incorporated into PR template as a checklist? Examples below.

I'd say that this could help with discoverability for first-time users. I think that contributors who go and read the docs on their own will be fine. On the other hand, more procedures can be overwhelming and discourage people... Maybe a positive wording would mitigate that?


Can you help our maintainers?
Change [ ] to [x] for guidelines you verified, or to N/A if they don't apply to your contribution.


Template as would be shown in the editor:

**Can you help our maintainers?**
Change `[ ]` to `[x]` for guidelines you verified, or to `N/A` if they don't apply to your contribution.

- [ ] [Writing style](https://docs.godotengine.org/en/stable/contributing/documentation/contribution_checklist.html#writing-style)
- [ ] [Code examples](https://docs.godotengine.org/en/stable/contributing/documentation/contribution_checklist.html#code-examples)
- [ ] [Manual style and formatting](https://docs.godotengine.org/en/stable/contributing/documentation/contribution_checklist.html#manual-style-and-formatting)
- [ ] [Images and videos](https://docs.godotengine.org/en/stable/contributing/documentation/contribution_checklist.html#images-and-videos)
- [ ] [GitHub metadata](https://docs.godotengine.org/en/stable/contributing/documentation/contribution_checklist.html#github)

@tetrapod00
Copy link
Contributor Author

tetrapod00 commented Jan 29, 2025

In principle that's a good idea!

I do have a few concerns:

  • I don't know how often people read the PR template 😄. We already have some information in the template, but frequently get PRs that target the wrong branch. Part of that was bad link defaults which we recently fixed.
  • A long checklist in the PR template might scare off first contributors who are really just trying to fix a typo or clarify a sentence.
  • If we put the checklist as text that is visible (I think we have to if we want the markup for interactable checkboxes), are we expecting most contributors to skim that and actually check, then check the boxes? If we hold the same standard to frequent contributors who know the rules, it's additional burden. If we allow frequent contributors to either check them all by habit or delete the section, it's a bit of a double standard, perhaps.
  • It also might invite unnecessary argument if a contributor explicitly checks a box to say they did something, and a maintainer disagrees that it's actually done?
  • If we put the checklist inside a comment as we currently do, the links don't work, I think?

At the very least I think we should add to the PR template a link to the checklist page as a whole; whether a full checklist is good to include is a good question.

@Maarrk
Copy link
Contributor

Maarrk commented Jan 29, 2025

At the very least I think we should add to the PR template a link to the checklist page as a whole

I think this is the most reasonable solution, I may have been overenthusiastic on my first two days being able to use the engine at work 😅

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area:contributing Issues and PRs related to the Contributing/Development section of the documentation content:new page Issues and PRs related to creation of new documentation pages for new or undocumented features discussion
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add a contributor checklist for godot-doc contributions
2 participants