search

ukmars / ukmarsbot

A simple beginners multi purpose robot platform
MIT License
67 stars 17 forks source link

When Github can't render a 'Source' file type, provide 'derived' Github-renderable format too. #4

Closed gbulmer closed 1 year ago

gbulmer commented 4 years ago

This is a 'meta' issue.

However the the files: ukmarsbot/docs/UKMARSbotBOM.xlsx ukmarsbot/docs/function-selector-resistors.xlsx are 'source' files which would need to have 'derived' files uploaded to the repo too.

In general only 'source' files should be stored in a repo. However, the repo is made easier to browse by a user if 'source' files which Github does not render into a browser format is also accompanied by a Github-renderable format. By definition, that second file is 'derived'.

A Github-renderable file-format allows someone to browse the repo directly, without needing to download the file to read its contents. It makes sense to make the repo easy to browse with minimal assumptions about their computing environment for UKMaRSBot's intended audience.

Specifically accompany .xlxs (or other none renderable data format) with a tab separated 'derived' data file. Many spreadsheet apps can generate this format. Github likes the file suffix to be '.tsv'. Then Github can detect and render the data as a table.

I have not checked, but AFAIK Github can do file comparison on .tsv files too.

Useful reference: The unreasonable effectiveness of GitHub browsability

micromouseonline commented 4 years ago

I agree. The spreadsheets should be in CSV format. Github is happy with the .csv extension as well as .tsv.

My preference would be CSV rather than TSV since is is, arguably, more common. By 'arguably' I mean that I do not recall ever seeing a file with the extension .tsv :)

On the subject, while Eagle files are text and so admirably suited to git version control, PDF versions of the schematic seem to be more friendly and a set of ready-to-go Gerbers would make it easy for anyone to submit the for manufacture.

micromouseonline commented 4 years ago

I have modified the contribution guidelines to omit the request for a label when submitting issues since this appears not to be available to non-contributing users.

gbulmer commented 4 years ago

I agree. The spreadsheets should be in CSV format. Github is happy with the .csv extension as well as .tsv.

I did not say 'spreadsheets should be in CSV format'. I said a Github-renderable derived file should be uploaded too. If the source file is .xlxs, then it should be in the repo anyway, otherwise there is the new issue of how to back up and share it which Github already solves.

My preference would be CSV rather than TSV since is is, arguably, more common. By 'arguably' I mean that I do not recall ever seeing a file with the extension .tsv :)

I would agree with you. However, I think I remember many, many years ago, that github wasn't smart about how it interpreted data files and rendered them, it just used the file extension. If that is fixed, and .csv files can be tab separated, then I agree that is better.

On the subject, while Eagle files are text and so admirably suited to git version control, PDF versions of the schematic seem to be more friendly and a set of ready-to-go Gerbers would make it easy for anyone to submit the for manufacture.

I agree pdf's are now rendered adequately by Github, so they are user-friendly. (That wasn't the case some years ago.)

I think a .zip file containing all the CAM files would be very useful and helpful. That would be 'ready-to-go' for manufacturing. I'm less convinced that uploading the individual files is essential.

micromouseonline commented 4 years ago

An unfortunate typo. It should have read "I have now modified . . ."

I have edited it to read correctly.

On 1 Aug 2019, at 00:32, G Bulmer notifications@github.com wrote:

I have not modified the contribution guidelines to omit the request for a label when submitting issues since this appears not to be available to non-contributing users.

I don't understand. If that point in the guideline can't be carried out by anyone other than contributors (who likely favour a specific label), what help is it? I've used Github before. I've raised issues on projects that I am not a contributor to. I started to raise an issue weeks ago, but gave up because I couldn't figure out how to label it.

Yesterday, I concluded that it is a guideline which are incorrect, see Applying labels to issues and pull requests

In repositories where you have write access

It was never possible for me, any other UKMaRS member, or anyone else interested, to follow all of the guidelines. The guidelines are, at best, misleading.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.