Checklist "how to contribute"

[NeoFromMatrix]

I'd suggest adding a checklist, giving information about how to contribute to the master pool. Especially oriented for first time contributors.

[fruchti]

I'm absolutely for a checklist or some more general contribution guide. @atoav had also proposed this in another issue.

In my opinion, a very detailed checklist would just end up as a duplication of the convention's rules and would be not that useful. Having a subset of the rules as a checklist might be an idea if we can select the rules based on how often new contributors got them wrong at first in the past. As this selection might change over time, we'd have to be careful not to let the checklist get too long, too.

Intuitively I'd prefer (at least at first) a more general view of steps for contributing, before we start elaborating individual rules. Some probably important “steps” coming to my mind:

1. Review the convention's rules for all parts of your contribution.
2. If you came across any ambiguous cases when reviewing the convention rules, check it's issues page and add your thoughts to the discussion or open a new issues to discuss you case.
3. Check if you can find a 3D model with a licence compatible to the pool's. KiCad's 3D models are in general compatible licence-wise. Do not include a 3D model with an unclear or proprietary licence!

This is far from a complete contribution guide, so I'd love to hear your thoughts on what such a checklist should look like!

[NeoFromMatrix]

Of course, keep it as long as needed and as short as possible (text and time wise).
You're probably right that the existing rules already cover a large part of this issue.

I'll tackle it from the other side. What I wanted to achieve:

• give newcomers info how they can contribute (maybe also info how the library works)
• documenting the process of "how a component enters the master library", super short example:
  • author creates the component and tests them on a PCB
  • author creates pull request with references attached (e.g. datasheets, proof of existing PCB), also stating if and how far he has tested it
  • someone else checks the pull request, verifies all checks have been done by the author and approves or gives feedback
• ensure quality components in the library (e.g. review process, proof of manufacturability)

[fruchti]

That sounds like a better approach, indeed. The main source of information how the pool is structured is currently the wiki, but it'd make sense to gather everything necessary in one place for new contributors, or at least have a short overview over the most important points.

I don't know if we should go as far as requiring an existing PCB. Especially for contributions without a new package this doesn't prove too much (e.g. not all pins on a microcontroller are used so an error in the pinout is still possible).

Review processes for the contributions are very important in my eyes as well. IMHO, there should be a more detailed checklist one could just go through when reviewing a PR. Though, we can address that completely separate from the contribution guide, can't we?

[NeoFromMatrix]

Yep, please consolidate the information at one spot. I didn't know about the wiki yet.

Indeed, PCB proof is pretty demanding. (but might be a side product if you make your footprints for a project) My goal would be to ensure a quality of the lib, because one error can pretty much make an entire PCB unusable. PCB proof would be another independent path comparing to something generated from the datasheet. Might also be too much, but independent paths for verification are always nice.

I share your opinion on the importance of the review process. Probably could be discussed in another issue. Still: someone making contributions will probably want to know about the review process, to make sure the contribution is conforming and the verification process goes smooth and fast. (hopefully avoiding designing the contribution around the requirements)

[fruchti]

Yep, please consolidate the information at one spot. I didn't know about the wiki yet.

The most beginner-friendly way to present this might be a step-by-step tutorial for a basic part creation case. This would for example immediately make the significance of the different parts of the pool (units, entities, etc.) clear and could provide links for further reading with more details on specifics.

My goal would be to ensure a quality of the lib, because one error can pretty much make an entire PCB unusable.

I absolutely agree for a production-grade library but I'm not sure if we are at that point yet. I'd propose a process to guarantee library dependability for the future based on two “pool levels”: One “verified pool“ with strict correctness guarantees and one “beta pool” with little restrictions for contribution (a superset of the verified pool). These would be just separate branches of the same repository. The process could look as follows:

• User A creates a microcontroller and opens a PR for the beta pool.
• Reviewer B confirms that the part is convention-compliant and merges the PR.
• User C shows a picture of a assembled board with the footprint. C confirms that the footprint and 3D model are correct.
• User D used all IO pins in some project and can confirm that the pin mapping is correct.
• etc.
• As soon as all points on a (to be defined) checklist are confirmed by reviewers or other users, the part can be merged into the “confirmed” pool.

This has a number of advantages:

• Contribution is easy because the contributor isn't solely responsible for everything.
• Discussion can be started early: WIP PRs aren't really possible if a finished board is required for a PR.
• News users would get the confirmed pool by default and can be certain of the parts' correctness.
• Users could opt-in to use some parts from the beta pool. That way it is clear which if their parts they have to explicitly double-check, while they easily have access to all parts.

This process can be viewed as an extension of our current structure: If we decide to implement it, we'd just consider the current pool the beta pool and slowly fill the confirmed pool from it.

That being said, I don't think we should implement such a process just now. Horizon frequently gets new features and some of them have their impact in the convention rules or require changes to existing parts. In other words, I don't think we have reached levels of stabilisation of Horizon itself where it makes sense to discuss matters of guaranteeing pool correctness as that inevitably makes a pool evolution slower. Additionally, the community is currently not that large.

[atoav]

Yep, please consolidate the information at one spot. I didn't know about the wiki yet.

Consolidation of Information

Consolidation was also my goal when I suggested to move information about the different PCB Layers directly into the software's sidebar. I think our goal first and foremost should be to eliminate potential questions and confusion at the root of the problem. Every process that becomes self explainatory (user doesn't has to leave the software to figure things out), is a win.

Of course we should give the pre-install-experience some thought. Right now there is a number of repos for a number of purposes, and the wiki in the main one. These Github Wikis tend to work well unless you exceed a number of pages or want to structure information in a better way. In the long term I suspect it might be better to have some sort of seperate webpage that is meant for users, while the github repos should be focused on development and contribution.

Making video tutorials on the basic usage is on my list of things I want to do once we have a release.

Component Rating System

As soon as all points on a (to be defined) checklist are confirmed by reviewers or other users, the part can be merged into the “confirmed” pool

I like the gist of the idea (in fact I had a similar idea myself). What I am not so sure about: maybe it is a better idea to make this part of the components themselves? So instead of having a pool with verified components and moving things from A to B constantly, we would have a pool with parts of various degrees "credibility".

In a dream world this would be part of the parts selection and pool manager itself. When you place a part in your schematic, the heads up display tells you the part hasn't been independently checked. So you click on a button, the part opens in the pool manager and you can click on "I checked the parts dimensions", "I checked the parts pinout", "I sucessfully soldered it on a PCB" etc. This check is registered and tied to that part at that time.

If you are paranoid while designing you just switch the "verified" filter on and set the count to 10 or something like that. Of course that would also need a mechanism to doubt the validity of a part etc.

As for now this is mostly a manual process. Maybe it is also not bad that way.

[atoav]

The documentation for horizon was moved from the github wiki to readthedocs.io. I think it makes sense to represent pool related contribution information in there.

I suggest:

• Discussions about pool conventions should still take place in this repo
• Whenever we come to an conclusion, we post an issue on the horizon-docs issue page as a reminder what needs to land in the docs

For now it is clear that we need to collect all contribution information in some way, and create a contribution page (maybe in a "pool" section within the docs).