Repository navigation
Improve contribution guide #7100
Description
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.
Activity
Moumouls commentedon Dec 30, 2020
@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 commentedon Dec 30, 2020
@mtrezza on my first contribution, I remember that running
npm run watchand then playing withnpm testwas not easy to understand the first time.Today, systems like
Jestcan onboard the compilation to only neednpm testand get rid off thenpm 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 watchcould 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 commentedon Mar 13, 2021
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
@TomWFox what's your opinion as chief docs officer?
TomWFox commentedon Mar 16, 2021
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 commentedon Apr 16, 2021
@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 commentedon Apr 23, 2021
I would be happy to work on it!
mtrezza commentedon Apr 23, 2021
Great! In terms of modification, it should transition from its current form of anecdotal account to a neutral guide:
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:
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.