Contributions: Guidelines, Reliability and Management

[dkebler]

Opening this for discussion about how want to ask members for contributions, what guideline to follow and how to indicate reliability (testing) of contribution.

We so far have some basic guidelines that are in the root readme file.

I repost them here.

Contributing

If you want to make a contribution (i.e. a folder of code) then follow these steps

1. Start a discussion topic in the discussions category corresponding to the primary subfolder where you think your contribution will be best placed.
2. Fork the repo then clone your fork to your dev machine.
3. Add your contribution folder under the appropriate primary subfolder (see above)
4. Make sure to edit the parent README.md file with a link to you contribution README.md
5. Make sure your folder adheres to the guide below
6. Push your committed changes back to your fork at your GitHub account
7. make a discussion post in the corresponding category with a link to your Github fork
8. Once others have vetted your contribution (via the discussion) create a PR in issues of your fork
9. Have the maintainers merge your PR (THANK YOU!)

Folder Guide

your contributed folder needs to have a README.md file

in the README.md file you need at least

• a link to download your folder. see how
• a clear explanation of the files in your contribution and how to use them
• a link back to the parent README.md file [return](../README.md)
• for code blocks there is no Berry language syntax highlighting but if you choose ```javascript you get some appropriate highlighting

also edit the parent directory README.md file and add a link to your README.md

[my contribution](my-contribution-folder/README.md)

It was also remarked that we should indicate the level of reliability of the contribution (testing)

So maybe we should have some kind of tags

untested

• marginally tested by contributor
• well tested by contributor
• tested by one other member
• tested by several members
• battle tested

[btsimonh]

I just submitted a PR without the discussion...
Personally, I think the PR is a good place for discussion of the PR? the contibutor can be asked to move it if necessary, etc.

Let's see how this one goes. Don't give me special treatment - treat it as a random contrib?
And be as critical as you can! We want to wring out how to respond meaninfully to stupid PRs.... so try being mean, and we'll find a compromise on the approach to take?

[sfromis]

I agree that having the discussion in the PR thread makes sense, this works well when users submit a PR for inclusion in the Tasmota project, without first starting an extra thread.

Only downside I've noticed is in case of a PR needing significant structural change, where it may be deemed easier to close it, to start a new, and thus a new discussion. However this does not happen often, and thus not much of a "problem". Of course the new PR can get a link to the old closed one, for reference.

[dkebler]

Regardless of any PR "discussion" my idea is to have a never closed discussion topic for that particular contribution, and a link to in the contribution's readme.

This is not so much for the contributor and those vetting the contribution PR but for initial brainstorming and for those wanting to use it later who have questions etc.

So IMO a discussion should be started before even an initial PR is set. As in "I have an idea for contribution". Later after a PR is submitted then PR related discussion can happen there (and the discussion topic can have links to PRs opened or closed) so as not to "clutter" the discussion topic.

This makes it clear (at least to me). I look at contribution's readme. I have questions about the using the contributions. I the see the link to the corresponding discussion topic (never closed). Aha! Maybe my question has already been answered. I also know how to then contact the contributor (rest of the community) with my question about this contribution. I don't have to make yet another topic on the same contribution, making it more likely we don't keep answering the same questions again and again.

[dkebler]

so I guess I need to add this to the "readme" guidline.

• a link to download your folder. see how
• a clear explanation of the files in your contribution and how to use them
• a link back to the parent README.md file [return](../README.md)
• a link to the corresponding Discussion topic
• links to each PR (optional)
• for code blocks there is no Berry language syntax highlighting but if you choose ```javascript you get some appropriate highlighting