Improve contribution guide
jgierer12 opened this issue · comments
Is your feature request related to a problem? Please describe.
As I wanted to contribute a few resources, I noticed a few things that made contributing a bit inconvenient. See details below.
Describe the solution you'd like
First of all the contributing guide seems like a generic template that doesn't really fit this project (e.g. the following paragraph, which seems to not apply to this project at all)
Increase the version numbers in any examples files and the README.md to the new version that this Pull Request would represent. The versioning scheme we use is SemVer.
It's great that you have a Code of Conduct, but it should go into a dedicated file CODE_OF_CONDUCT.md in order for GitHub to link it in the right places, and so it doesn't pollute the contribution guide.
Instead, I feel like most of README.md (everything up until the "Built With" section) should instead be moved into the contribution guide.
As was already brought up in #147, currently it's not apparent that you use git flow and PRs should be made against dev instead of master. This should definitely explained in CONTRIBUTING.md.
Additional context
All this might seem like unimportant nit picking, but IMO a good contribution guide is one of the most important parts of an open-source project. It allows newcomers to the project to get a quick and frictionless introduction to the workflow and conventions of the project.
That means it both increases the incentive to contribute in the first place, as well as reducing the effort needed by the maintainer(s) to review contributions.
I also noticed that the project doesn't use Prettier for auto-formatting which meant that my VSCode applied wrong formatting every time I saved, which made it a little annoying to work with. But that's out of scope for this issue, and I get that not using Prettier might have perfectly justified reasons.
To make that clear, I think you already have a very good starting point for a contribuition guide, just in the wrong place (README.md). So putting together a good basic CONTRIBUTING.md wouldn't be too much effort. I would be happy to implement the changes I suggested if you agree with them.
The idea of having a contributing.md is good. At first I thought there is no need for it, since people won't read it anyways. That's why most of the info is in the readme.md. We can sure exclude it from there and just reference it.
In my experience, people started reading it a lot more since GitHub started linking it when opening issues and PRs. For some people (like myself :D) it can be the deciding factor to start contributing to a project.
I will start a draft just moving the existing parts from readme to contributing and the code of conduct into its own file and open a PR. From there we can decide whether there needs to be additional content or not.