learnosity-qti icon indicating copy to clipboard operation
learnosity-qti copied to clipboard

Published 20 hours ago • verified publisher icon Learnosity

Add a CONTRIBUTING.md

Open ttton opened this issue 5 years ago • 11 comments

To aid new contributors, we should include a concise guide on how best to contribute code to the official repository. It should describe as simply as possible the process for contributing, guidelines for reviews and code quality, the git flow and any caveats or limitations.

The guide should follow standard conventions used in other public git repositories, so that it is as easy as possible to discover and follow.

Thoughts / ideas / suggestions?

Feel free to drop your thoughts in below about what the contributing guide should cover, its format and any other ways we could make life easier for contributors.

ttton avatar May 29 '19 07:05 ttton

Ideas of things to include:

  • PSR-compliance
  • whitespaces changes
  • testsuite (ran and/or added)

shtrom avatar Jun 03 '19 06:06 shtrom

I would add to this list:

  • Guidelines to commits / PRs
  • Summary of review / merge process

ttton avatar Jun 05 '19 01:06 ttton

  • Documentation
  • Code comments and doc blocks

ttton avatar Jun 05 '19 07:06 ttton

  • Copyright assignment

shtrom avatar Jun 06 '19 00:06 shtrom

We can use this as a reference for PSR-2 compatibility: https://www.php-fig.org/psr/psr-2/

Other things to consider including or mentioning:

  • PHP_CodeSniffer and automatic code correction (phpcs / phpcbf)
  • Licensing (and copyright) etc.
  • https://phptherightway.com (as a guide on PHP best practices)?

ttton avatar Jun 06 '19 02:06 ttton

Notes on good commits: separate lint/whitespace, refactors, bugfixes, and features. Keep each commit as a single consistent and meaningful piece of work.

shtrom avatar Jun 07 '19 06:06 shtrom

  • Consistent coding style and usage of syntax/idioms (e.g. treatment of colon-syntax control structures)

ttton avatar Jun 12 '19 01:06 ttton

According to the current composer.json, this library is licensed under GPL 2.0; I wonder if, to make it clearer to contributors, it's better to also include a copy of the license in a LICENSE.md and reference it in the contribution guide?

ttton avatar Jun 12 '19 04:06 ttton

I think it would be good, yeah.

On Wed, 12 Jun 2019 at 14:17, Trungtin Ton [email protected] wrote:

According to the current composer.json https://github.com/Learnosity/learnosity-qti/blob/develop/composer.json#L11, this library is licensed under GPL 2.0; I wonder if, to make it clearer to contributors, it's better to also include a copy of the license in a LICENSE.md and reference it in the contribution guide?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/Learnosity/learnosity-qti/issues/43?email_source=notifications&email_token=AABHEGDFLLI6LSAMUOSJXWLP2B2EVA5CNFSM4HQJ2H72YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODXPGKYA#issuecomment-501114208, or mute the thread https://github.com/notifications/unsubscribe-auth/AABHEGGCUJVQYREGUYJKJSDP2B2EVANCNFSM4HQJ2H7Q .

shtrom avatar Jun 12 '19 04:06 shtrom

Add a PR template, too, with the most important checkboxes (phpcbf, tests, ....)

shtrom avatar Jun 13 '19 01:06 shtrom

This is probably a useful reference in terms of inspiration for content: https://github.com/symfony/symfony/blob/4.4/CONTRIBUTING.md

ttton avatar Jun 18 '19 00:06 ttton