docs: Update informal contributing guide #5890

damianpm · 2024-12-12T14:43:06Z

Hi!
I want to start contributing to the project, so I've been following the informal contributing guide, and I've found it's outdated.

Changes proposed in this PR:

Add .vscode/settings.json, including the recommended settings
Add .vscode/extensions.json, including dbaeumer.vscode-eslint in the "recommendations" array
Get rid of the "Using Visual Studio Code" section
Updated reference to Neostandard, instead of StandardJS

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

Fdawgs · 2024-12-12T16:10:54Z

Thanks for the PR @damianpm.

As you've noted, the guide is outdated and could do with a revamp:

VS Code settings mentioned should be moved to .vscode/settings.json so contributors don't have to set it themselves
Add a .vscode/extensions.json with dbaeumer.vscode-eslint in recommendations array
Get rid of the Using Visual Studio Code section, shouldn't need to teach contributors to suck eggs
We use Neostandard now, so the Standard mention (and link) should be updated in Setting Up Your Environment section

damianpm · 2024-12-12T16:35:02Z

, the guide is outdated and could do with a revamp:

Hi @Fdawgs sure, I'll update the PR

damianpm · 2024-12-13T09:35:31Z

@Fdawgs I've updated the PR, let me know if I'm missing anything else

Fdawgs · 2024-12-13T09:42:46Z

Thanks @damianpm. @jsumners from looking at git blame this was your guide, wdyt?

jsumners · 2024-12-13T10:59:30Z

I didn't have a chance to review before now. I was in agreement that the guide needed updating in regard to some links and a bit of text. I also wanted to ask @voxpelli if the eslint references are still relevant with neostandard.

VS Code settings mentioned should be moved to .vscode/settings.json so contributors don't have to set it themselves

Add a .vscode/extensions.json with dbaeumer.vscode-eslint in recommendations array

Get rid of the Using Visual Studio Code section, shouldn't need to teach contributors to suck eggs

I completely disagree with all of this.

The original guide did not require the reader to download any files from this repo, and didn't require us to add an unnecessary .vscode directory to the repo.
I don't care one little bit what editor/ide anyone is using. But VSCode is very popular and comes with a price tag of $0.00. The guide uses it give the reader a basic environment to use for contributions. It is not the only way to do things. We just don't need to write a guide for every possible editor. People can apply the knowledge to their own preferences.

I would revert this PR to commit a068946 (#5890) and then update the content as necessary.

mcollina

lgtm

.gitignore

.vscode/extensions.json

Co-authored-by: James Sumners <321201+jsumners@users.noreply.github.com> Signed-off-by: Damián Peralta Mariñelarena <damianpm@users.noreply.github.com>

voxpelli

if the eslint references are still relevant with neostandard

@jsumners Yes, the ESLint extension is the correct one, we opted for keeping ESLint compatibility when making neostandard, to make editor compatibility easier :)

voxpelli · 2024-12-13T13:33:55Z

.vscode/settings.json

+{
+  "[javascript]": {
+      "editor.defaultFormatter": "dbaeumer.vscode-eslint",
+      "editor.codeActionsOnSave": {
+          "source.fixAll": "explicit"
+      }
+  },
+
+  "workbench.colorCustomizations": {
+      "statusBar.background": "#178bb9"
+  }
+}


I'm 👎 on this, see eg. microsoft/vscode#206802

I find it quite jarring when my settings are changed due to an .vscode/settings.json – and unless all contributors are forced to use VSCode it feels odd to enforce this just on VSCode. Use eg. git hooks on push to avoid having people push unformatted code.

A better way is to make it a devcontainer and add this as part of its vscode customization section: https://containers.dev/supporting#visual-studio-code

One can make this a devcontainer template that Fastify repositories can easily set up: https://containers.dev/implementors/templates/

The original guide detailed setting up a Fastify specific VSCode instance. Again, I would revert this PR to commit a068946 (#5890) and then update the content as necessary.

voxpelli · 2024-12-13T13:39:28Z

.gitignore

@@ -142,7 +142,7 @@ pnpm-lock.yaml
 yarn.lock

 # editor files
-# .vscode
+.vscode


Should probably make it:

.vscode/* !.vscode/extensions.json

I would keep ignoring the directory. One of the reasons I wrote the guide the way I did is so that we wouldn't have to include this directory at all. The editor is going to update any file in the directory, and will result in extraneous data in PRs.

The .vscode/extensions.json is the one useful file

Oh, I misread it. Yeah, that suggestion makes sense. 👍

damianpm · 2024-12-16T13:17:10Z

Hi @voxpelli, @jsumners, @mcollina, @Fdawgs !

Let’s try to recap, we should:

Put back the “Using Visual Studio Code” section?
Keep both .vscode/settings.json and .vscode/extensions.json files?
Keep ignoring the .vscode directory?

voxpelli · 2024-12-16T15:22:39Z

I think:

Keep .vscode/extensions.json file, remove .vscode/settings.json, make .gitignore be:

.vscode/*
!.vscode/extensions.json

And maybe partially re-add "Using Visual Studio Code" to describe how to configure those extensions, if deemed necessary, I don't think it is really.

jsumners · 2024-12-16T20:46:09Z

I don't see a point in the guide if it doesn't result in a configured editor that applies our desired formatting. Otherwise, the guide is:

Clone
npm install
git push
Wait for CI to tell you it's all busted, repeat 3 and 4

damianpm · 2024-12-16T21:33:18Z

OK, here's my two cents:

As a developer, I already have a code editor, in my case it's VSCode, so I don't want to have another instance of the same editor.
I think that adding VSCode as a requirement to contribute may be unnecessary, people may prefer to use another code editor, or use Vim, or a plain text editor.
Nonetheless, VSCode is my favorite editor, and it may be useful if most people in the project use it. Then, I'd include it as a recommendation.
The section "Using Visual Studio Code", should state that this is optional, not mandatory. It won't ask you to have a separate instance, but only to use the recommended extensions and settings
I'd keep both files, .vscode/settings.json and .vscode/extensions.json
Keeping .vscode/settings.json is OK, since it applies only to this workspace
I'd keep ignoring the.vscodedirectory, so people cloning the repo will get the recommended extension and settings, but won't be able to commit changes

jsumners · 2024-12-16T23:09:50Z

As a developer, I already have a code editor, in my case it's VSCode, so I don't want to have another instance of the same editor.

You don't have to follow the guide. It's there for people who don't know things. You can read what it does and then apply the concepts the way you like.

jsumners · 2024-12-16T23:11:13Z

I think that adding VSCode as a requirement to contribute may be unnecessary, people may prefer to use another code editor, or use Vim, or a plain text editor.

It isn't a requirement. It is an example and simple setup for developers that want to utilize what the project deems as a baseline setup. Use whatever you like. I don't use VSCode at all.

cecia234 · 2025-05-22T20:12:29Z

Hi everyone,
A few weeks ago I opened #6119 since I noticed that a correction could be made to the "Using Vscode" section of the informal contributing guide, and @Eomm pointed me to this PR.

I see that the PR is still open and the discussion stalled. @damianpm would you like some help?
Even if the ./vscode files do not get merged, contributors could still benefit from the updates to "Using Visual Studio Code" section!

cecia234 · 2025-06-21T16:15:23Z

Hi, just following up to see if there's anything I can do to help move this PR forward.
Since no one is actively working on it, I’d be happy to open a new PR with just the "Using Visual Studio Code" correction.

jsumners · 2025-06-21T20:48:15Z

You are quite welcome to pick up on this work. I suggest incorporating the work and feedback from this PR by following https://gist.github.com/jsumners/461ef7a64545108635cc437fde112721

cecia234 · 2025-06-22T08:34:56Z

Thank you for the infos!
Just to make sure, changes to extensions.json and settings.json are not needed anymore, right?

Update contributing guide

a068946

github-actions bot added the documentation Improvements or additions to documentation label Dec 12, 2024

Adress feedback: move settings to .vscode, update liks

df86314

damianpm force-pushed the update-contributing-guide branch from ddfd2ee to df86314 Compare December 12, 2024 17:18

Merge branch 'main' into update-contributing-guide

b0e427b

Fdawgs requested a review from jsumners December 13, 2024 09:42

mcollina reviewed Dec 13, 2024

View reviewed changes

.gitignore Outdated Show resolved Hide resolved

damianpm changed the title ~~Update informal contributing guide~~ docs: Update informal contributing guide Dec 13, 2024

Ignore .vscode

fb514e3

damianpm requested a review from mcollina December 13, 2024 11:38

jsumners reviewed Dec 13, 2024

View reviewed changes

.vscode/extensions.json Outdated Show resolved Hide resolved

Update .vscode/extensions.json

1c5f4a9

Co-authored-by: James Sumners <321201+jsumners@users.noreply.github.com> Signed-off-by: Damián Peralta Mariñelarena <damianpm@users.noreply.github.com>

voxpelli reviewed Dec 13, 2024

View reviewed changes

Eomm mentioned this pull request May 13, 2025

Wrong VSCode settings file suggested in "informal contributing guide" #6119

Closed

Uh oh!

docs: Update informal contributing guide #5890

Are you sure you want to change the base?

docs: Update informal contributing guide #5890

Uh oh!

Conversation

damianpm commented Dec 12, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

Fdawgs commented Dec 12, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

damianpm commented Dec 12, 2024

Uh oh!

damianpm commented Dec 13, 2024

Uh oh!

Fdawgs commented Dec 13, 2024

Uh oh!

jsumners commented Dec 13, 2024

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

voxpelli left a comment

Choose a reason for hiding this comment

Uh oh!

voxpelli Dec 13, 2024

Choose a reason for hiding this comment

Uh oh!

voxpelli Dec 13, 2024

Choose a reason for hiding this comment

Uh oh!

jsumners Dec 13, 2024

Choose a reason for hiding this comment

Uh oh!

voxpelli Dec 13, 2024

Choose a reason for hiding this comment

Uh oh!

jsumners Dec 13, 2024

Choose a reason for hiding this comment

Uh oh!

voxpelli Dec 13, 2024

Choose a reason for hiding this comment

Uh oh!

jsumners Dec 13, 2024

Choose a reason for hiding this comment

Uh oh!

damianpm commented Dec 16, 2024

Uh oh!

voxpelli commented Dec 16, 2024

Uh oh!

jsumners commented Dec 16, 2024

Uh oh!

damianpm commented Dec 16, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jsumners commented Dec 16, 2024

Uh oh!

jsumners commented Dec 16, 2024

Uh oh!

cecia234 commented May 22, 2025

Uh oh!

cecia234 commented Jun 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jsumners commented Jun 21, 2025

Uh oh!

cecia234 commented Jun 22, 2025

Uh oh!

Uh oh!

damianpm commented Dec 12, 2024 •

edited

Loading

Fdawgs commented Dec 12, 2024 •

edited

Loading

damianpm commented Dec 16, 2024 •

edited

Loading

cecia234 commented Jun 21, 2025 •

edited

Loading