Style: clarifications to "Introduction to Contributing"

[LauraLangdon]

Type of feature

🎨 Style

Current behavior

1. In the "Setup" section a first-time contributor might not know (or might appreciate a refresher) on how to fork and clone a repo.

2. In the "Testing" section it's not stated whether this step applies to the docs, but I don't think it does. Running npm test in this repo gives npm ERR! Missing script: "test", and I don't see any tests in this repo.

3. In the "Pull Requests" section

   1. The bolded line under the section heading reads "We actively welcome your pull requests, however linking your work to an existing issue is preferred," but item 10 in the instructions below says "Unsolicited code is welcomed, but an issue is required for announce your intentions. PR's without a linked issue will be marked invalid and closed." These are somewhat contradictory, with the first suggesting a linked issue is preferred and the second saying a linked issue is required.

   2. In item 1, some contributors might like a guide to creating branches.

   3. In item 3, how should a contributor decided whether the code they've written should be tested?

   4. In item 5, contributors might benefit from knowing where to store images they'd like to add if there's a particular directory for images, and how to refer to a file in the image directory within the directory in which they're making changes.

4. In the "Issues" section, the sentence "... please assign yourself by commenting on the following word .take" is maybe slightly confusing.

5. In the "Funding" section, the link to funding.yml is broken, and seems to possibly not be applicable currently anyway.

Suggested solution

1. Add a link to the GitHub doc on forking and cloning a repo and clarification about changing the link in the codeblock to the contributor's own cloned repo link.

2. Add clarification, either on how to fix this error, or that this step does not apply to changes made in the docs.opensauced.pizza repo.

3. 1. These two sentences should be brought into full agreement, affirming either the preference or requirement for a linked issue.
   2. Perhaps a link to branching would be helpful.
   3. Add clarification about when testing is needed.
   4. Add instructions about where to store images and how to refer to them from other directories.

4. This could maybe be rephrased to something like "... please assign yourself by commenting on the issue with .take".

5. Change or remove the sentence "If you have made any contributions to the projectd directly or indirectly, please consider adding your profile to the funding.yml."

Additional context

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

Contributing Docs

• I agree to follow this project's Contribution Docs

[0-vortex]

Hey there, sorry for the late reply, this is a really extensive ticket, will try to cover everything as needed :D

2. In the "Testing" section it's not stated whether this step applies to the docs, but I don't think it does. Running npm test in this repo gives npm ERR! Missing script: "test", and I don't see any tests in this repo.

This is a more general truth related to most of the open-sauced repositories, running npm t will obviously fail if the repository doesn't enforce it. While the docs repo (this one) has most of the workflows open-sauced has, it doesn't feature tests of any kind since it's mostly about adding text. The introduction guide is actually designed for https://opensauced.pizza wonder what thoughts you have on making that information more available.

1. The bolded line under the section heading reads "We actively welcome your pull requests, however linking your work to an existing issue is preferred," but item 10 in the instructions below says "Unsolicited code is welcomed, but an issue is required for announce your intentions. PR's without a linked issue will be marked invalid and closed." These are somewhat contradictory, with the first suggesting a linked issue is preferred and the second saying a linked issue is required.

That whole section wording could definitely improve - a missing issue is not making the PR automatically close, that used to be the case in the past and now we have mtfoley/pr-compliance-action, slowly communicating everything that a first-time contributor needs to do to get the PR up and running.

5. In the "Funding" section, the link to funding.yml is broken, and seems to possibly not be applicable currently anyway.

Yes, indeed that functionality has moved and is now being managed by open-sauced/.github

As for the other pointers, I mostly agree, except for the tutorials, links appreciated but wouldn't side track with that based on project specifics unless required by actual contributors - for example, if you contribute to a frontend project, it's most likely going to use Vite so a lot of opinionated decisions and knowledge would come from that, like public folders, static assets, etc; similarly an Octokit implementation would not share its quirks in the introduction guide. Individual repositories could simplify some of their Readme.md's by linking to the introduction guide first and then revising the differences.

In some cases, some of the repositories we maintain have advanced tech faster than we could adjust the docs for them outside of the Readme.md or have an opportunity to apply the new standards to all existing repositories. To be honest, this repository and docusaurus as technology did not get many contributors, it's likely that the changes you proposed would be done by me (unless you want to do it).

IMHO a better way to get this ticket across is to spread it across 3 good-first-issues:

• cleaning up git and github tutorial links
• correct wrong on divergent sections
• add additional content related to some features like funding, the dot github repo and where to look for extended contribution guides for each repository (the readme)

[LauraLangdon]

Thanks for the reply, @0-vortex!

While the docs repo (this one) has most of the workflows open-sauced has, it doesn't feature tests of any kind since it's mostly about adding text. The introduction guide is actually designed for https://opensauced.pizza/ wonder what thoughts you have on making that information more available.

It might be worth considering adding tests for broken links, spelling, and accessibility. I've just added/am nearly finished adding tests for our docs at Suborbital (also using Docusaurus!), and I'd be happy to duplicate those here if that would be helpful.

To be honest, this repository and docusaurus as technology did not get many contributors, it's likely that the changes you proposed would be done by me (unless you want to do it).

I'd be happy to take care of these as long as I wouldn't be stepping on any toes!

IMHO a better way to get this ticket across is to spread it across 3 good-first-issues:

• cleaning up git and github tutorial links
• correct wrong on divergent sections
• add additional content related to some features like funding, the dot github repo and where to look for extended contribution guides for each repository (the readme)

That makes sense! I'll set those up and close this one?

[CBID2]

Thanks for the reply, @0-vortex!

While the docs repo (this one) has most of the workflows open-sauced has, it doesn't feature tests of any kind since it's mostly about adding text. The introduction guide is actually designed for https://opensauced.pizza/ wonder what thoughts you have on making that information more available.

It might be worth considering adding tests for broken links, spelling, and accessibility. I've just added/am nearly finished adding tests for our docs at Suborbital (also using Docusaurus!), and I'd be happy to duplicate those here if that would be helpful.

To be honest, this repository and docusaurus as technology did not get many contributors, it's likely that the changes you proposed would be done by me (unless you want to do it).

I'd be happy to take care of these as long as I wouldn't be stepping on any toes!

IMHO a better way to get this ticket across is to spread it across 3 good-first-issues:

• cleaning up git and github tutorial links
• correct wrong on divergent sections
• add additional content related to some features like funding, the dot github repo and where to look for extended contribution guides for each repository (the readme)

That makes sense! I'll set those up and close this one?

I vote yes @LauraLangdon

[BekahHW]

I think it would be worth re-writing this issue into smaller issues since some updates have been made. @diivi made updates that covered some of this and I'm sure that other PRs have as well. I'm not sure we need tests right now, but I'd be curious about your approach to testing docs, @LauraLangdon.

[LauraLangdon]

Sorry for the radio silence; I lost track of my notifications! I think this issue was pretty much solved by #63, so I'll close it unless anyone disagrees (or anyone else can feel free to close it, ofc 😊).