• Please review our updated Terms and Rules here

Why does building something from Github have to be in a "secret" language and needlessly archaic with no real instructions?

Well thankyou to everyone who gave answers, insight, and posted thier take and experiences. I do feel I have learned something from all of this.
 
dabone said:
If I wasn't selling the boards, I don't think I would have invested the time to fully document them.
Click to expand...
I feel the same way about the revision I did to the Brain Board (By Mike Willegal); it's highly unlikely I would have documented it properly and published it properly to Github like I did if I were not selling a few of them or offering kits. GPL also brings obligations of course, and I'm more than happy to keep things in the open under GPL, but for me that is something to abide by more than the primary reason for publishing. The primary reasons for publishing a project like this are that I've sent some out into the world, and that I want anyone to be able to easily make one without any physical supplies from me.

If I publish a project to github I feel like it should at least have a decent readme, and be in a state where someone shouldn't be completely lost if they stumble upon it. But as others have said, many use it as their own personal storage/sharing grounds more than a place to publish [well] documented works. As a small silver lining, it's usually evident within a couple minutes if a repository is properly documented or if you're going to be roughing it (or if it will even be useful at all).

It's definitely a lot of work to manage anything with any substantial number of pull requests or forks. Doing that kind of repo management as not-for-profit work just isn't for most people. But on the flip side, for something you maintain that may be of interest to others, there are definitely advantages to having it on GitHub.
 
I have a couple of projects on github, and could probably do a better job with the instructions. After walking some folks through building the firmware, and sending the firmware to others, I configured github to compile and publish the firmware on every commit, but now that kicad can be called from the command line to generate files, I should probably automate the generationg of gerbers, boms, and instructions. It's a lot of work though. But seeing people use the projects and getting the occasional thanks makes it worth the effort.
 
I have a question for folks using Github. If you have content, and you delete that content. There is an annotation that says something (lets say a folder and its contents) were deleted and when. IS there a log area where reasons why changes were made? Shouldn't there be? I am on one repository for a board. I had a couple test boards printed. The directories were up a couple months. I figured thats a bit of time to see if bugs need to be ironed out. I sent away for a couple boards. I go back on github. And the folder with that boards gerbers and files are removed, stating deleted but no reason given.

How does one keep track of long term projects if they are incapable of keeping records of changes?



So sure we can all speculate. There was a problem with the circuit. Something was wrong. Again, this is just speculation. Why wouldnt there be notation explaining WHY IT WAS REMOVED!

Im chocking it up to how society is becoming daily more incapable of communication because of smartphones and Antisocial media. Everything is indirect. Nothing is documented.
 
Last edited:
VERAULT said:
I have a question for folks using Github. If you have content, and you delete that content. There is an annotation that says something (lets say a folder and its contents) were deleted and when. IS there a log area where reasons why changes were made? Shouldn't there be? I am on one repository for a board. I had a couple test boards printed. The directories were up a couple months. I figured thats a bit of time to see if bugs need to be ironed out. I sent away for a couple boards. I go back on github. And the folder with that boards gerbers and files are removed, stating deleted but no reason given.

How does one keep track of long term projects if they are incapable of keeping records of changes?



So sure we can all speculate. There was a problem with the circuit. Something was wrong. Again, this is just speculation. Why wouldnt there be notation explaining WHY IT WAS REMOVED!

Im chocking it up to how society is becoming daily more incapable of communication because of smartphones and Antisocial media. Everything is indirect. Nothing is documented.
Click to expand...
Often in github, even deleted files are in the history of branches, it depends. When you make a 'commit' (even deleting files), you're supposed to enter text / a message explaining the change.

I usually make sure to do a 'git pull' of the project to a local directory whenever I start working with it, and can choose to sync or not sync new changes by the project owner from there out.
 
skate323k137 said:
Often in github, even deleted files are in the history of branches, it depends. When you make a 'commit' (even deleting files), you're supposed to enter text / a message explaining the change.

I usually make sure to do a 'git pull' of the project to a local directory whenever I start working with it, and can choose to sync or not sync new changes by the project owner from there out.
Click to expand...
I have the files. I downloaded the repository before making a purchase. But now I am concerned for this build; why was it pulled? I am just wondering if there is a change log or something I am unfamiliar with.
 
I try not to use github anymore, and I don't know specifically the link you were looking at. I'll try to answer generally though. If a file shows up as deleted, it could be that it was actually renamed. In the git database, the original name is stored as deleted, and the file is now found somewhere else committed under a new name. This file deletion and creation would be contained in a single simultaneous commit with a message why.... if.... the maintainer is using git correctly under reasonable practices. I say this, because I have seen so many times, something as simple as this is not done correctly. If they renamed a file, but caused it to be done with only a delete in a single commit incorrectly, you won't see where it went because now it's not tied to the new file. I've seen it happen.

Another annoyance with a place like github is that they are more and more pushing the interface to be a mainly a browser of the files in the repository (i.e. it's like a file hosting site to the average person), rather than make the change history front and center, which is what a version control system like git is all about -- tracking changes. I've used git since day one, and really many other version control systems where it was easy to view the changes. When I use git (not github), I am usually viewing the history as the primary activity when I use git as a third-party to a project, I need to see the history to know what's going on. So one big reason why I stopped using github, is that I got tired jumping through hoops just to see what actually is happening by constantly clicking through screens to view the history. The offline standard git utilities are much better to use for researching.

Sadly, I think the site called github, is not really git if you only use the website. It's a site that pretends to be about git, but really it's just a file hosting site with almost no care of good practices in revision control. If github is your introduction into git, you have not learned git. Now if you use the about the only positive aspect in that github still allows you to use git locally by cloning the repository, now you are not using github, and you have complete freedom from them as a casual user to someone's repository. But a drawback if you wanted to use github as your hosting site too, and use git locally, is that you now have to jump through inconvenient hoops just to do a push it back, because they do things a little bit differently. Don't make me get into how they try to manage pull requests and can't turn off their version of it now that you are hosting something there.
 
VERAULT said:
I have a question for folks using Github. If you have content, and you delete that content. There is an annotation that says something (lets say a folder and its contents) were deleted and when. IS there a log area where reasons why changes were made?
Click to expand...
Yes; it's the log message for the commit that deleted the files. You can find it via the git log command or, probably much more easily, through one of the various GUI programs that lets you browse the log.

Just as an example, in my r8format repository you will not find a file called activate at the top level in the latest commit. But if you're wondering where it went, and why, you can ask Git for a history of that (now-nonexistent) file:

$ git log --stat -- activate
commit 0448e1c4bfe234462adc9ee9d03f25b1e86c8303
Author: Curt J. Sampson <cjs@cynic.net>
Date: Sat Jan 8 10:05:28 2022 +0900

activate → pactivate: Update python virtualenv setup script

From: https://github.com/0cjs/pactivate.git

We no longer explicitly specify `python3` as the interpreter: since
`pactivate` no longer takes an argument for this we'd instead have to find
the actual intepreter ourselves and create a symlink to it. That doesn't
seem worth the work; it's expected that much Python code won't work on
Python 2 these days anyway.

activate | 27 ---------------------------
1 file changed, 27 deletions(-)

commit 4ef0445b75e762b480bc1186e8b5260ef5cdcf98
Author: Curt J. Sampson <cjs@cynic.net>
Date: Wed Aug 19 20:32:36 2020 +0900

Test,etc.: Test framework and enough code to confirm it works

activate | 27 +++++++++++++++++++++++++++
1 file changed, 27 insertions(+)

Here you can see that that file has been changed in two commits: added in 4ef0445b (at the bottom) and removed in the later one, 0448e1c4. Note that this particular log query shows only that file, even if other things where changed in the commits; you can use other log commands to see all the changed files, the diffs, and other information. These commits can also be looked up on GitHub, e.g. 0448e1c4.

How good the log message will be depends on the developers, of course, and how close you are to the target audience of the commit message. I'll have more to say on this later, but keep in mind that commit messages are generally for communications between people commiting to the project, and they're going to write it in a way that works efficiently for them, which will generally assume some reasonable amount of project knowledge. (When reviewing code I certainly do not want to see long-winded explanations that go over the basics of the project in every single commit.)

It's probably worth noting that each commit in Git is a complete snapshot of the tree of all tracked files at that particular moment. Think of each commit as something like a ZIP file containing all the tracked project files. Thus there is nothing that was ever once committed that you cannot go back and recover. (And because Git is essentially a blockchain, given any particular commit you know that you have the full history if all the links in that chain are intact—the commits are linked via their SHA1 hashes so ancestor commits can never be changed.)

Also, regarding the3dfxdude's comments on GitHub just above, I don't think it's quite as bad as he makes it out to be. GitHub, GitLab and similar do several different things, of varying levels of utility:
  1. It provides free storage and serving of Git repos, so you can give anybody a URL and they can git clone https://github.com/.... This is extremely handy.
  2. It provides open on-line browsing of repos, with rendering of Markdown. This is also extremely handy, as I can give someone a link to a document or a source file and they can easily read it without having to use Git or download anything.
  3. It provides free identity management, authentication and authorisation, which makes it a very convenient place to store a shared repo to which I and others I authorise can push commits, to allow us to work together more easily. (This can fairly easily be done in many other ways, too, but it's nice that I can just know someone's GitHub ID and add them to my project, rather than having to go find their SSH public key, add those to my config files, give them appropriate URLs, and generally maintain my own system for doing this. That is always a fallback option, though, which is great.)
  4. It provides a plethora of other, more closed tools, such as issues, PRs, an automated build system, etc. etc. These too far free, but if for whatever reason GitHub decided they weren't going to be free any more, or just decided to shut down, it would be at the least a lot of work to get all that information out of GitHub's own databases and move it to another system, if indeed it could even be done at all. For that reason, I don't use these other tools so much.
 
Last edited:
In response to the original complaint, I'd like to point out that there's a whole pile of basic domain knowledge about using Git, building software and so on that most developers do not document in individual repos because it would be extremely tedious not just to rewrite all of that every time, but to read every time. Looking at some of the issues you experienced, such as
VERAULT said:
Again I tried this on windows.. Got nowhere. I loaded up a p4 laptop with lubuntu and tried it.
They say linux already has all the tools you need to do it.. Well thats a lie.. your distro MAY have the libraries but most likely you will have to add them. I had to add GIT. ...
So I Cloned the repository.. Ok whats the exact command
Click to expand...
Including stuff at this level in documentation for a particular repository would be kind of like including tutorials on ordering PCBs and soldering in every hardware repository. It's not trivial knowledge, no, but it's also just not practical to go from first principles of design and build for a particular work domain in every single project in that domain. Not least because such a verbose flood of documentation would hide the important information that reasonably experienced developers need.

commodorejohn said:
If your project has dependencies beyond stdlib and you don't state outright what they are and which versions in a human-readable form, you're a bad person and you should feel bad. Simple as that.
Click to expand...
VERAULT said:
Edit. And I cant believe I need to say this but of course I am grateful to the whole open source community and people who put projects up for everyone to share in. My problem is not with them but the seemingly systemic lack of documention, instructions, and communication. Thats what I am getting at.
Click to expand...
Well, I strongly disagree with commodorejohn's comment here, and the general idea that things shouldn't go up on GitHub (or similar places) without good documentation, instructions and so on.

Basically, what these sorts of comments seem to be saying is that, if a blob of code doesn't achieve a certain level of quality, it should be hidden from the world rather than made available. And that's been the bane of many an idea I've encountered: someone coded something up that was useful to some degree, decided the source wasn't good enough to make public, and often enough it gets lost to history. I can't tell you how many things I've found in old forum posts where if I'd had access to the code, even if it no longer worked, I could still have used that as a basis for my own code and/or improvements and it would have saved me a lot of time. But because people complain about code quality, lack of documentation, or whatever, it never gets posted and I'm stuck starting from scratch.

GitHub is not just a place for completed, fully documented projects. It's full of repos that are done but undocumented, only partially done, or even barely just started and then abandoned. That's fine: it's better that the code be out there for someone who has the knowledge to make use of it, even if that's only a few people, than it is lost forever and anybody else has to restart from scratch.

That's not to say I think people shouldn't bother to try to document things and provide proper build systems. I myself hate to see things like "run git submodule --init first" in documentation (and it's even worse when that's left out completely), which is why pretty much every project I work on has a top-level Test script that will do that for you, if it detects that that's necessary. (And do a lot of other automatic setup for you, where feasible, or at least tell you what dependencies you're missing and give you some clue on how to get them.)

But doing this kind of thing is a large amount of rather difficult work. I'm fine with it because my day job for the past few decades has included being a build engineer on some very complex build systems, and I'm pretty good at it. (And I'm also, admittedly, somewhat anal-retentive about this sort of thing so doing this scratches an emotional itch for me.) But I certainly see why someone who's got their own project running wouldn't want to spend a significant amount of time learning how to construct good portable build systems and then doing them for each project.
 
wrljet said:
What is a good tool for preparing the .MD files?
Click to expand...
Your favourite editor.

A primary design goal of Markdown is that it's easily readable as a regular old text file. While it's possible (and, sadly, not unusual) to write Markdown in a way that it not so easily readable as a regular text file, I myself avoid this. So here, for example, is an extract from the EE/7400.md file from my sedoc repo.

Code: 
7400-Series Overview
====================

Parts
-----

#### Notes

- See also Wikipedia, [List of 7400-series integrated circuits][wp-7400list].
- Part number is given without `74` prefix and logic family.
- Pin counts are for DIP parts.
- Inputs `A,B,C,…`, Outputs `Y0,Y1,…`, Enable `G1,G̅2̅,/G2…` or `CS1,C̅S̅2̅,/CS2`

#### Boolean

Inverter/buffer:
* __'04__ (14): Hex inverter gate [SN74LS04]
  - Pins: `1A 1Y 2A 2Y 3A 3Y GND   4Y 4A 5Y 5A 6Y 6A Vcc`
  - Open collector: __'05__; __'06__ 30V/40mA; __'16__ 15V/40mA.
  - Non-inverting: '06 → __'07__; '16 → __'17__.
  - Schmitt-trigger: __'14__ [SN74LS14], __'19__ [SN74LS19]

NAND:
* __'00__ (14): Quad 2-input NAND gate [SN74LS00]
  - Pins: `1A 1B 1Y 2A 2B 2Y GND ‥  3Y 3B 3A 4Y 4B 4A Vcc`
  - Open collector verssions: __'03__ Iol=16 mA; __'38__ Iol=48 mA
* __'01, '39__ (14) Quad 2-input NAND gate, open collector
  - Pins: `1Y 1A 1B 2Y 2A 2B GND ‥  3A 3B 3Y 4A 4B 4Y Vcc`
  - Iol: '01=22 mA, '39=60-80 mA

.... (stuff removed) ....

#### Multivibrators

_Astable_ continually switches between two states,
_monostable_ settles in one state when not triggered,
_bistable_ settles in either state.

* __'122__ (16): Retriggerable monostable multivibrator [SN74LS122]
  - Like '123 with internal resistor available, no separate clear/timing inputs.
  - Pins: `A1 A2 B1 B2 C̅L̅R̅ Q̅ GND ‥ Q Rint NC Cext NC Rext/Cext Vcc`
  - Trigger input A is active-low, B active-high and avoids jitter.
  - Retrigger after 0.22 Cext (pF) extends pulse. Clear terminates pulse.
  - Timing cap between Cext and Rext/Cext (positive).
  - Connect Rint to Vcc to use internal timing resistor.
* __'123, '130__ (16): Dual retriggerable monostable multivibrator [SN74LS122]

.... (stuff removed) ....

ASCII Pinout Diagrams
---------------------

        Blu

                        ┌──∪──┐ '244
        Blu       →  1G̅ │1  20│ Vcc         Red
        Gre      -> 1A1 │2  19│ 2G̅  →       Blu
        Yel    <-   2Y4 │3  18│ 1Y1   ->    Yel
        Gre      -> 1A2 │4  17│ 2A4 <-      Gre
        Yel    <-   2Y3 │5  16│ 1Y2   ->    Yel
        Gre      -> 1A3 │6  15│ 2A3 <-      Gre
        Yel    <-   2Y2 │7  14│ 1Y3   ->    Yel
        Gre      -> 1A4 │8  13│ 2A2 <-      Gre
        Yel    <-   2Y1 │9  12│ 1Y4   ->    Yel
        Blk         Gnd │10 11│ 2A1 <-      Gre
                        └─────┘

        Blk     Gnd
        Red     +5
        Blu     enable
        Gre     input
        Yel     output

<!-------------------------------------------------------------------->
[ALUs]: gate.md#alus
[open collector]: https://en.wikipedia.org/wiki/Open_collector
[wp-7400list]: https://en.wikipedia.org/wiki/List_of_7400-series_integrated_circuits

[SN74LS00]: http://www.ti.com/lit/gpn/sn74ls00
[SN74LS02]: http://www.ti.com/lit/gpn/sn74ls02
[SN74LS04]: http://www.ti.com/lit/gpn/sn74ls04
[SN74LS08]: http://www.ti.com/lit/gpn/sn74ls08
[SN74LS14]: http://www.ti.com/lit/gpn/sn74ls14

.... (stuff removed) ....

You'll note that this is completely readable as ordinary text, and in fact that's my most common method of viewing it: I just bring it up in my editor. It's not even necessary to have syntax highlighting, though that is an additional bonus. (Mine looks like the attached image.) I also happen to have editor macros that let me, e.g., put my cursor on a link reference and copy the link to my cut buffer, so I can immediately paste it into a web browser. (I've been too lazy so far to tweak it just to automatically open the link in my browser. :p)

You can also look at these files in rendered formats, as per the link above, but while this is great for just pointing someone at a particular piece of documentation (including linking to headings within it using e.g., .../7400.md#ascii-pinout-diagram), I usually find that my editor is easier to use even for reading, given that it has much better search capabilities than "Find in page..." of a typical web browser.

Especially when getting used to Markdown it can be convenient to see rendered results in real time. Some editors, such as Visual Studio Code, have this built in (or perhaps it's a plugin), so as you edit the text you see the changes in the rendered version right beside it. I myself use a tool called grip that lets me open a link in my browser to an arbitrary Markdown file on my system and updates the page displayed in the browser whenever it sees the file change. This particular program has the advantage that it uses GitHub's Markdown formatter and CSS so what I see there is pretty much exactly how it will be shown on GitHub.


1706897239368.png
 
Last edited:
I appreciate the Input @cjs , but we covered all of that last year. Not trying to rehash old arguments but pose a brand new question. I really was only wondering about changes and change-logs in particular.
 
VERAULT said:
I appreciate the Input @cjs , but we covered all of that last year. Not trying to rehash old arguments but pose a brand new question. I really was only wondering about changes and change-logs in particular.
Click to expand...
Sorry, but I thought that in this post I covered exactly your question about changes and change logs, and I did not see any answers to your questions/comments, "IS there a log area where reasons why changes were made?", "I am just wondering if there is a change log or something I am unfamiliar with," and "How does one keep track of long term projects if they are incapable of keeping records of changes?" I got the impression that you weren't clear on what exactly Git commits are and how the commit logs work, since to an experienced Git user the place to go look to answer these questions is fairly obvious.

(In particular, from your comment, "There is an annotation that says something (lets say a folder and its contents) were deleted and when," I got the impression that you didn't understand that a deleted file is deleted only for that version (and subsequent versions, until re-added), and that anybody who clones the Git repo after that is still getting a complete copy of the older version that includes the "deleted" files.)

As for the remainder of that post, and my other post, I read through this entire thread before posting and felt I was contributing things that had not yet really be pointed out here. Sorry if you felt those were just a "rehash."
 
I wrote a completely revised (70% changes) firmware for a github project. I can't figure out how to incorporate it meaningfully. So I haven't.
 
Chuck(G) said:
I wrote a completely revised (70% changes) firmware for a github project. I can't figure out how to incorporate it meaningfully. So I haven't.
Click to expand...
Well, it's certainly up to you whether you want to do the work that "incorporates it meaningfully" or not; there's no reason you should be expected to do a bunch of extra work that you don't feel up to doing.

But here's what you can do to make what you've done available to others so that someone else can use it, and even perhaps do the incorporation work:

  1. Click the "Fork" button on the upstream repo so that you have a copy of the repo in your GitHub account. (To be clear, this is not a declaration that you want to "fork" the project in the sense of making a competing project; this is just because GitHub, rightfully, only lets the owner of a repo or those he/she has authorised to push commits up into the copy of the repo on their account.)
  2. Push your changes up into your copy of the repo on a development branch, or even on the "main" branch in your copy if you don't intend to do any further work on it.
  3. File a PR in the upstream repo with a brief description of your changes and why they're useful, and point out that you've not done whatever it is that needs to be done to "incorporate" the changes to your satisfaction.
  4. Ignore it from that point onwards.
This will make your code discoverable and accessible to anyone. (Even if you don't file a PR, people will
still be able to find your fork and the code in it via the "Fork" drop-down menu.)

If you're particularly lucky, someone like me will come along and not only find your code useful, but will do the integration work to get it into a form suitable for bringing back on to the main branch of the upstream repo.
 
You must log in or register to reply here.
Back
Top