Add contributing guide

[jsumners]

This pull request starts an informal guides section within the documentation by adding a new "contributing" guide. As discussed in #2574 (comment), we should started a concerted effort to separate our reference documentation from our informal guides. I see this PR as the first step in that process.

Additionally, I recently learned that it is possible to isolate VSCode instances such that each instance can have its own settings and set of extensions. Thus, this PR includes a guide on setting up such an instance specifically for working with Fastify. The idea being, that people can use a Fastify specific instance of VSCode so that their normal workflow does not conflict with our standards.

Note: I modeled this guide after https://github.com/github/opensource.guide/blob/2868efbf0c14aec821909c19e210c3603a4a7805/CONTRIBUTING.md

Checklist

• run npm run test and npm run benchmark
• tests and/or benchmarks are included
• documentation is changed or added
• commit message and code follows the Developer's Certification of Origin
  and the Code of conduct

[mcollina]

@jsumners @lmammino can you make sure the guides/ folder is rendered on the website as well?

[jsumners]

I don't know how.

[jsumners]

@fastify/core anyone know how to move this forward?

[mcollina]

@lmammino is our man!

[lmammino]

Trying to run this on a local build of the website. I'll attach some screenshots shortly

PS: Great initiative @jsumners, I love this PR!

[lmammino]

Ok, after a closer look, I am realizing this is currently not compatible with what our current website build expects in terms of files structure.

This is because we currently build the table of contents from the section ## Documentation in the project README.

All (previous) links are in the form:

/docs/<some-name>.md

Here we are introducing an additional level of nesting such as:

/docs/Guides/<some-name>.md

In order to make this work, I can see several options:

1. We will need to update the build process to support nested documentation files (I can try to work on this next week)
2. Keep the "guides" pages in the main folder (and not in the Guides subfolder). We could use a filename schema such as Guides-Index.md and Guides-Contributing.md. Probably this is the simplest approach, but there might be unexpected side effects on how the website gets rendered. I would want to test this.
3. If we think this section will grow significantly on its own, we can handle it separately and detach it from the docs section (in the website it will be displayed in its own section, with its own ToC). This requires more work and more thinking, so I am a little bit hesitant on this option right now.

Unfortunately, I won't have much time this week for open source activities. But I am happy to collaborate on this from next week and make sure everything will work on the website before we merge this one.

Meanwhile, please do let me know if you have any strong preference on any of these options.

[mcollina]

I expect this "Guides" Section to grow significantly over time, and we will move some of our current docs as guides as well. So maybe the best option is 3?

Maybe we should render this with a tree TOC:

 / v3.3.3
| - API
     | - Server.md
     | - Request.md
     | - ...
| - Guides
     | - Contributing.md
     | - Plugins.md
     | - Migrate to V3.md
     | - ...

(we also need to keep supporting the previous structure.

[jsumners]

I'd be okay with a new structure as Matteo proposes, but we should still fix things so that a deeply nested structure is possible.

[jsumners]

@lmammino any movement here?

[jsumners]

What do I need to do to make this happen?

[lmammino]

@jsumners, sincere apologies for disappearing here.

Got swamped in a couple of super busy weeks (still ongoing) and this totally faded from my mind.

I'll try to run some experiments between tonight and tomorrow morning and update you here with my progress.

At best I'll have a PR for the website repo ready for review by tomorrow. 🤞

[jsumners]

Cool. I was really just asking if there's anything I could do.

[lmammino]

Now that I have been playing with this a bit more, I have a question which might affect the implementation significantly:

Do we want to tie the guides to specific releases or not?

I mean, do we want to generate a "page" for every doc item per release (e.g. /docs/v3.7.x/Guides/Contributing) or do we want to keep the guides separated and always fetch them from master (e.g. /docs/Guides/Contributing)?

Given my current understanding of the scope for guides, I think it would be best to keep the Guides high level and process/render them separately from the docs for various versions.

Would you agree?

[jsumners]

I think they should be part of the versioned docs.

[lmammino]

Fair point, then I will try to follow the schema suggested also by @mcollina

[lmammino]

Started this: https://github.com/fastify/website/pull/215

Having nested sections in the docs adds a bunch of complexity that was not initially accounted for. I have made a todo list of what's missing and I will keep chipping away at it as I have some free time during the next week.

Sorry if I am being a bit slow at this

[lmammino]

I forgot to mention that what was suggested by @mcollina:

 / v3.3.3
| - API
     | - Server.md
     | - Request.md
     | - ...
| - Guides
     | - Contributing.md
     | - Plugins.md
     | - Migrate to V3.md
     | - ...

Might be achievable by moving the files that belong to "API" in a dedicated subfolder in the repo. I hope that this matches your expectations.

Also, let's keep in mind that we will have to maintain the doc structure for older versions, so we will see the changes only for master and new releases as we apply these new changes.

[jsumners]

I fixed the anchor links in the guide TOC.

Would you be opposed to docs/{reference,guides}?

[lmammino]

Would you be opposed to docs/{reference,guides}?

I personally like "reference" more than "api"

[Eomm]

I mean, do we want to generate a "page" for every doc item per release

I agree that they should be part of the versioned docs

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[mcollina]

Should we put this guide into CONTRIBUTING.md?

[jsumners]

Should we put this guide into CONTRIBUTING.md?

This PR adds a note to CONTRIBUTING.md that informs the reader to also read this informal guide. I see CONTRIBUTING.md as a formal set of rules and this guide as a "great, we're glad you want to help out, here are some suggestions for making that easier."

What we really need is someone with enough time to implement documentation sectioning on the website so that this PR can be merged. Then this doc would be more visible.

[RafaelGSS]

Wow, I've missed this one. There are missing something or are able to land?

[jsumners]

@RafaelGSS please read back through the thread. We need https://github.com/fastify/website/pull/215 to be solved.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[jsumners]

With https://github.com/fastify/website/pull/269 landed (thank you @luisorbaiceta!) we can finally merge this.

[luisorbaiceta]

With fastify/website#269 landed (thank you @luisorbaiceta!) we can finally merge this.

You're welcome! I will see if I can find time to work on some other issues. Till next time!

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.