search

waterloo-rocketry / electrical_standard

Rules and guidelines for electrical projects
1 stars 1 forks source link

Modify documentation standards to reflect move to github #6

Closed akmorrison closed 6 years ago

akmorrison commented 6 years ago

There's a couple places in the standard that we dictate to "put things on the drive". Specifically, final versions of code, schematics, and all documentation. There's a few issues with the drive, mainly

  1. The files don't belong to the team (they remain tied to the uploader, and the uploader can remove them at any time, and the file storage size counts against the uploader's account)
  2. The drive isn't well organized for electrical stuff (do I put this schematic into my projects folder, or into the schematic folder, or what?)
  3. There's no version control (not actually sure if this is an issue, but I believe everything should have easily viewable history).

Moving all documentation to Github solves all these issues, since the new waterloo-rocketry is a team organization, not tied to a person (and with infinite (I think) storage space). Things are naturally organized by project, and it's easy to include discussions, notes, and code/schematics/whatever files with their entire history, all tracked in git. Plus then everything can be done from the command line, and that speaks to my inner bad-hollywood-movie-hacker.

I motion that we change the documentation section (and probably the software section) to reflect that documentation/schematics/code/whatever shouldn't be put on the drive (or at least, not exclusively on the drive), and all projects should have their own repo on here where that stuff is tracked.

Thoughts?

akmorrison commented 6 years ago

discussion about this issue happened on slack starting here, https://waterloorocketry.slack.com/archives/C07MX0QDS/p1513986122000023, the conversation ends at 9:29 on 2017-12-24.

Most important points from that discussion are that there was agreement that documentation should be put in the github repo so that it's with the rest of the project, but all "release" versions for documentation should be archived on the drive, so that it's with the rest of the documentation, and it's easily viewable for non-electrical members of the team who don't use github.

Discussion of issues/PRs/commits/changes/whatever can take place on slack, but permalinks to these discussions should be posted on github so that it's easy to view the discussions from about the issues from the issues.

jacobdeery commented 6 years ago

Electrical folder on the drive has also now been reorganized (thanks @amihaila!)