Contributor's guide for hyperSpec

[ximeg]

Why contributor's guide is a good idea?

How to contribute to the project? What git branches to use? How the code review is conducted? These are stumbling blocks for many developers.

Therefore it is paramount to have an established set of simple and logical, but strict rules that everybody has to follow. Their violation often leads to unpleasant surprises, misunderstanding, and can result in an unexpected urgent work for some of the team members to bring the project back on track. And this can be very bad.

This is why a we need a contributor's guide in a written form.

How to make one?

There is an article on GitHub that outlines the recommended approach - Setting guidelines for repository contributors

What questions should be addressed?

• Rules of git use in the project - nobody commits directly to master, instead we work with branches according to the git flow model.
• Core review - pull requests are subjects to review via pull requests
• Traceability - issues are opened for the community to discuss the work to be done before it is done. These issues are linked to the feature or bugfix branches and pull requests.
• Licensing - contributors understand that their work forever becomes the part of the hyperSpec project and is going to be licensed under free open source license

[ximeg]

Make a draft of the contributor's guide

[ximeg]

I like this idea of including emoji into the commit messages that I discovered in the Atom's guidelines. GitHub renders them as pictures.

• Consider starting the commit message with an applicable emoji:
  * 🎨 :art: when improving the format/structure of the code
  * 🐎 :racehorse: when improving performance
  * 🚱 :non-potable_water: when plugging memory leaks
  * 📝 :memo: when writing docs
  * 🐧 :penguin: when fixing something on Linux
  * 🍎 :apple: when fixing something on macOS
  * 🏁 :checkered_flag: when fixing something on Windows
  * 🐛 :bug: when fixing a bug
  * 🔥 :fire: when removing code or files
  * 💚 :green_heart: when fixing the CI build
  * ✅ :white_check_mark: when adding tests
  * 🔒 :lock: when dealing with security
  * ⬆️ :arrow_up: when upgrading dependencies
  * ⬇️ :arrow_down: when downgrading dependencies
  * 👕 :shirt: when removing linter warnings

Do we want to use this practice in our project?

[cbeleites]

I'd prefer to use a more directly descriptive "tag" verb. Either something like
bugfix: ... or fix issue #... : <explanation, refactor ....
Possibly also because I do a good part of my git work in the shell.

[bryanhanson]

I’m OK with any useful scheme, but like Claudia I do all my git work in the shell so shorter is better.

…

On May 13, 2020, at 12:22 PM, Claudia Beleites ***@***.***> wrote: I'd prefer to use a more directly descriptive "tag" verb. Either something like bugfix: ... or fix issue #... : <explanation, refactor .... Possibly also because I do a good part of my git work in the shell. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#112 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABCIPV67QI3DSFTABQWAQDRRLCLXANCNFSM4M6IEV5A>.

[bryanhanson]

We have a solid CONTRIBUTING.md so can we close this issue? Obviously we can make changes in the future but the basic principles seem to be established.

[ximeg]

Yes, I agree, it's done and may need only small polishing in the future!