Updates to CONTRIBUTING.md

[chrisdel101]

This task was noted as comments in various miscellaneous places, but wanted to make a note of the ongoing work.

Work will include:

• Expanding the document(s) overall word count to be more descriptive and give more information (and be more helpful).

• Giving specific beginner friendly examples of how to get started, i.e how to find files, how to get started.

• Giving specifics about what we expect in the code i.e. no prettifying, match style of current file's code, others?

  • Now we've started a bit of an informal style guide, it will good to communicate this to contributors before they commit.
  • Following issue #1596, maybe we want to consider implementing an official code style guide? (@bjohansebas is doing, and has done, many things to improve alot of this). A discussion to be had another day...

• Telling contributor to open an issue and GET APPROVAL before making a PR.

• Tell them we expect both the description sections to be filled out, both for the Issue, and the PR.

  • I'm of the mind that we discard any submissions where these are left empty. Can I put this in? That we don't expect empty submissions?

• Inform about the ability to use the preview feature.

• Inform about the PR process (Submit issue-> Submit PR-> Review process-> Merge).

I was also thinking: We could add a contributions section promoting the expressJS documentation, expressjs.com, to the contributing HTML page on the website itself? Adding this could be a useful way to promote contributions and the standards we expect. Either we'd put it at the bottom of the current page, or add a new page somewhere.

This issue will only handle CONTRIBUTING.md for the repo.

[bjohansebas]

We could add a contributions section promoting the expressJS documentation, expressjs.com, to the contributing HTML page on the website itself? Adding this could be a useful way to promote contributions and the standards we expect. Either we'd put it at the bottom of the current page, or add a new page somewhere.

Could we add back the 'edit page' function in the footer, which was removed in #1548?

[bjohansebas]

It would be good to add that the API documentation does not need to be translated.

[chrisdel101]

UPDATE: I have been working on this. Have the copy done. Just working on the delivery. There will be a new contribution-docs.md for expressjs.com under the resources tab, based on Rand's comment. The CONTRUBING.md will link to that - then we don't have any repeated content, and this way we have just one source of truth for the text.

[chrisdel101]

Could we add back the 'edit page' function in the footer, which was removed in #1548?

What do you mean by this? I checked out the commit a1af54da before that issue and the footer looked like this. I don't see any edit page button.

Also,

1. What does the file get-contributing.sh do? That code is impossible to understand.
2. I'm altering the CONTRIBUTING.md and pointing people to the new page on the website, so I want to make sure that script doesn't affect this.
3. How do translations work? What does it mean translated by Strongloop? I just want to know if the section is correct https://github.com/expressjs/expressjs.com/blob/gh-pages/CONTRIBUTING.md#contributing-translations.
   • Is there some translating happening in the build process? I'm not really sure what happens in the Check Translation build checks.

[bjohansebas]

What do you mean by this? I checked out the commit https://github.com/expressjs/expressjs.com/commit/a1af54da092f70b4630b37327a56efe65b36bbc4 before that issue and the footer looked like this. I don't see any edit page button.

That's the message on the main page, but for the other pages like 'Hello World', the text 'fork the website on GitHub' changes to 'edit this page on GitHub'

What does the file get-contributing.sh do? That code is impossible to understand.

This file brings the content of the contributing file that is in the express repository, I'm not really sure how the code works

How do translations work? What does it mean translated by Strongloop? I just want to know if the section is correct https://github.com/expressjs/expressjs.com/blob/gh-pages/CONTRIBUTING.md#contributing-translations.

Strongloop no longer exists, this comment has more context than I do (https://github.com/expressjs/expressjs.com/issues/1647#issuecomment-2425149812)

Is there some translating happening in the build process? I'm not really sure what happens in the Check Translation build checks.

It only checks that the files edited in English have also been edited in the other languages. If they haven't been edited, it adds a label to indicate that the modified files require translation into the other languages. It's not working properly yet due to a permissions issue, but we're already working on solving this

I'm altering the CONTRIBUTING.md and pointing people to the new page on the website, so I want to make sure that script doesn't affect this.

If you alter the contributing file on this repository, it won't be reflected on the website, but if you modify it in the express repository, it will.

[chrisdel101]

Ahh okay thanks for all info. It looks like that contributing.sh might not be used anymore, at least looking at the commit history. (Oh wait, maybe it brings into the markup itself)

Maybe I’ll make a PR of what I have and see if it’s something that you think will work.

[bjohansebas]

contributing.sh is still used, it’s part of the workflow to bring in external documentation. I think we need to move those files into .github.