review repository idea and items in it

[amchagas]

Hi!
Thinking about the next steps for this project, I thought it would be a good idea to have a repository template that contributors could use when they are developing tools, so that a certain uniformity is present, making it easier for people to go through different repositories and contribute.

This is a very initial sketch of this idea, and I would like as much input as possible at this point, including why this might be a terrible idea.

so please, when you have time, do take a look through and give me a piece of your mind! :)

Also let me know if the idea is not clear!

[vektorious]

Just to get it into my head: You are talking about something they could copy and fill it with their information to present/document their tool/product?

Just to get the discussion started. Why do you think this is needed?

[amchagas]

Yes, I'm thinking about a template people can easily "fill out" and have a "standardized" repository.

Take our own projects for instance:
https://github.com/amchagas/flypi/
and
https://github.com/vektorious/lightM

They are organised in different ways, although they could have the same structure. There are some printed parts, some electronics and some code, all of these could be organised in the same folder/file structure. Having both projects organised in the same way would:
a) make it easier for people to navigate both, even when they had only seen one of them before. (and here I'm thinking on users and reviewers/collaborators)
b) make it easier to see which parts could be used in other projects.

[vektorious]

Well, I agree with you! I think the biggest advantage might be that projects might get better documented ;)

But we have to agree on a structure. I actually like yours quite a lot. I'm not sure if it would make sense to have a code folder with all the Arduino etc things. We could try and polish our repositories and motivate others to do the same in order to list them as example repositories for OSH projects.

There are also a lot of resources from Mozilla Open Leaders on how to build a good project repository!

[amchagas]

There are also a lot of resources from Mozilla Open Leaders on how to build a good project repository!

cool, do you happen to have the links to those resources handy?

Also, could you add a bit why you think having a folder with all Arduino(and other microcontrollers/programmable) things wouldn't make sense?

[thessaly]

Hey, good idea. Also, @vektorious is right, from Mozilla Open Leaders there are many useful things.

Here is a presentation on READMEs I remixed from the program.

In general, if the project is open I'd ask for:

• One sentence explaining what the device does (similar to mission/vision in MozOL)
• LICENSE.md
• CONTRIBUTING.md

In particular for the case of hardware projects, my ideal repo would have:

• Bill of Materials with aprox cost, links to recommended suppliers' (this is one example)
• Fritzing diagram or equivalent for the electronics
• If the project involves some sort of sending data somewhere, I appreciate simple diagrams like this clarifying workflow
• Links to datasheets of components
• All the code in one place
• Current status of project: I think badges are super useful, like in this example, though I don't know if they exist for hardware. Would love to see some showing if there is someone from the team working on it or not, if the project works or there are failures... etc

It's a lot, but I said ideal :P

[emdupre]

This seems great -- I'm (almost) always pro templating ! 😺

I wonder if we couldn't work off of the structure that's been developed for standardizing small software projects, with tools like cookiecutter and shablona.

[vektorious]

Well I think I can't add more to what @thessaly wrote. Here is the link to the Mozilla program,

Well I think all code should be in one place and then separated for on which device it is going to run. Mainly a personal preference?

The two example tools for software are great and I think we can use a lot of their structure.

[thessaly]

Good idea @emdupre! We can contribute to cookiecutter with a template, it's a win-win. I didn't know about shablona, looks cool.

+1 @vektorious with that personal preference

[amchagas]

Thanks for the comments and links everyone!!

+1 for creating a template that could be added to Cookiecutter. Didn't know this existed to be honest. Thanks! @emdupre Which brings to the next question, has anyone worked with it and could take on the task of creating a package for it when we are done deciding what should be in the template? or induce me on how it works so I can do it?

@thessaly Some of your suggestions are already there (BOM and datasheets and all code in one place), I wonder if bringing them down to the "root" of the repo would help? Or even adding this tree structure in the readme.md like in Shablona? (Which I like quite a bit :) ) Having diagrams explaining where data comes from and where it goes is also a good idea!

@vektorious did you think about something like this?

[vektorious]

@amchagas I really like the tree structure because it clarifies the structure a lot but (IMHO) it is ugly as fuck...

Well maybe putting it in the end and set a link at the top would be a work around for that 😄

And yes, the structure the software folder has now is what I meant.