Improve contribution guide

[mtrezza]

New Issue Checklist

• I am not disclosing a vulnerability.
• I am not just asking a question.
• I have searched through existing issues.
• I can reproduce the issue with the latest version of Parse Server.

Issue Description

The Contribution Guide could benefit from an overhaul to:

• be more accessible for new developers by reducing required pre-existing knowledge
• mitigate bug risks by documenting processes for common changes
• facilitate code quality by adding code style guidelines

The contribution guide currently only contains descriptions of the technical set-up required to make changes to Parse Server, described in way that assumes a level of pre-existing knowledge about tools and processes that has shown in some cases to discourage new developers from creating PRs. Parse is not just an entry point for new developers for its use as a backend but also when it comes to its development and making first steps into open-source contribution. A more accessible guide benefits both developers and further development of Parse.

Suggested changes

• Add process: Add new Parse Error -> Improve contribution guide #7075
• Add process: Add new Parse Server configuration parameter -> Improve contribution guide #7075
• Add: Code style guide
• Add: PR guide (GitHub guide is too verbose and not suitable as a reference for new developers)
• Reformat document to increase readability
• Rewrite guides into step-by-step instructions to help new developers

Please feel free to grab one or propose others.

[Moumouls]

@julianvogels could help us to improve this one 🙂 (ref: https://community.parseplatform.org/t/what-you-love-about-parse-and-also-of-the-difficulties-you-have-encountered/1140/5 )

[Moumouls]

@mtrezza on my first contribution, I remember that running npm run watch and then playing with npm test was not easy to understand the first time.

Today, systems like Jest can onboard the compilation to only need npm test and get rid off the npm run watch.

I know https://www.npmjs.com/package/concurrently that allow to execute 2 commands at the same time.

I found that Jasmine do not have watch mode: jasmine/jasmine-npm#5

So by adding nodemon + concurrently + npm test + npm run watch could do the trick.

i also found that we can add the babel compiler to our jasmine.json: https://github.com/piecioshka/test-jasmine-babel/blob/master/test/jasmine.json

[mtrezza]

I stumbled upon a brilliant open source, multi-lingual, multi-dev-environment guide for first contributors that we could link to in our contribution guide: https://github.com/firstcontributions/first-contributions

It includes How-Tos for

• Git CLI as well as GitHub Desktop
• VS Code

@TomWFox what's your opinion as chief docs officer?

[TomWFox]

Looks neat, there are some parts which wouldn't apply for our projects (e.g. make changes - could cause a bit of confusion but perhaps easily outweighed by the benefit of the resource).

[mtrezza]

@dblythy Would you want to make a PR in ref to this issue to add a modified version of your blog post to the contribution guide, for the reasons outlined in the comment? If not, no worries, I will put it on my list.

[dblythy]

I would be happy to work on it!

[mtrezza]

Great! In terms of modification, it should transition from its current form of anecdotal account to a neutral guide:

• more compact instead of verbose prose format (use lists, 1-2-3 step-by-step)
• imperative form instead of 1st person reference (e.g. "Do this and that" instead of "I did this and that")
• shape it into community editable form, expecting that others will amend and refine it in the future; that also means you don't have to produce additional content from what's already there (screenshots, etc), that can always be done by community edits
• merge it into the existing contribution guide, we don't want to add just another section

To not just add more content to the contribution guide, we should create a structure that provides an index with overview and allows to deep dive when necessary. For example, the first thing in the contribution guide should be a simple index that links into the respective document section, like:

• Set up local environment
  • Install Visual Studio Code
  • Install Node.js
• Download repository
  • Install GitHub Desktop
• Prepare for change
  • Create new branch
• Add test
  • ...
• Submit PR

As part of the change, a lot of the current technical instructions should be added only as alternative info, such as git CLI commands. For new developers git CLI commands are not necessary, they can use GutHub Desktop and experienced developers don't need to be instructed on how to use the git CLI anyway.