discussion: tooling support / rules for contributors

[NoNameProvided]

This issue aims to continue the discussion about tooling in #162.

Currently there are no really good way to know what style and schemes should be followed when contributing to the project. we should cover the following topic:

Changelog

Changelog is not auto-generated, but made by hand. This way we can left things out from it which is important to not to do. To fix this, and autogenerate we should use something like the Angular commit format. Description for the usage is the folllowing:

We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history. But also, we use the git commit messages to generate the our change log. (Ok you got us, it's basically Angular's commit message format).

type(scope): subject

Type

Must be one of the following:

fix: A bug fix feat: A new feature docs: Documentation only changes style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) refactor: A code change that neither fixes a bug nor adds a feature perf: A code change that improves performance test: Adding missing tests chore: Changes to the build process or auxiliary tools and libraries such as documentation generation Scope

The scope could be anything specifying place of the commit change. For example, the name of the plugin being changed

Subject

The subject contains succinct description of the change:

• use the imperative, present tense: "change" not "changed" nor "changes"
• do not capitalize first letter
• do not place a period (.) at the end
• entire length of the commit message must not go over 50 characters

When we follow these rules, there are various tools to generate our changelog.

Git flow

Git flow is a branching model, and help organize the work. It has a nice intro here: http://nvie.com/posts/a-successful-git-branching-model/

Contributing.md

A little starting guide to new contributors would help to lower the barrier to contributing. This should contain a setup guide and an overview about the structure and the workings of the project.

(Another thing, but the architecture and working details should be explained in a developer sections of the documentation. But for that first we should write documentation :D )

Contributors.md

Acknowledging the work of the contributors is never bad =) We should add a small description what users contributed to the project if it's a sensible part, and put a link at the bottom, to the contributors page of the project.

Coding style (and enforcing it)

Currently there are no way to figure out the coding style except reading the actual code. To fix this we can have an eslint test which we run on every git commit as a pre hook. The details for the config should be decided. Also a the check should be added to Circle CI as well to prevent merging branch when the code is not formatted properly.

An other easy thing can be to add .editorconfig file to help editors figure out the basic formatting rules.

[NoNameProvided]

I am happy to take on these. But let's discuss first what we want to use.

Also if anyone has a question I am happy to explain any of them in more details.

[MichalLytek]

To fix this we can have an eslint test which we run on every git commit as a pre hook

We have already a tslint.json but very liberal. @pleerock has to set it according to his coding style and then we could refactor the code and set the CI stuffs.

[pleerock]

• changelog

automatically generated changelog may sound as a good idea, but I don't think it gonna work in small projects like ours. First we need to make sure all commits named properly and maybe force contributors including first-coming contributors to follow naming strategy. This is really annoying to do for both them and us. I think its easier to control it by our own - simply when there is a PR ask author to add line into the changelog about what he did

• gitflow

we probably should have two branches - current master branch and "next" branch for the next version. Or we can name it as next version, e.g. 1.0.0 branch.

• contributing.md

something we should have. Would be great if someone spend some time and do this document

• Coding style

Im quite strong opinionated about coding style (sorry about it), so coding style should be based on what you can see right now in the code. Unfortunately I didn't had time to configure tslint properly because I need to explore each option of tslint to get know what it affects. Would be great if someone can configure it to match current code style

[github-actions[bot]]

Stale issue message