Yes, deliberately, because I felt I had something useful to add that hadn't already appeared in the thread. Again, sorry if you felt that conversation was done and didn't want to see further posts on it, but that's the nature of discussion forums.
I believe in documentation. My github code is not only documented at the source level, but a top-down doc is published external to the code.
I haven't, but I have read about it. So of course I will take you at your word.
My training was in the mainframe world that often involved many people in a project. You were expected to produce several documents as project manager. (1) Design document, outlining the basic operation and estimating the time and labor and other resources for implementation. (2) A project schedule; usually a Gantt chart--my own upper management had the maxim "If I can't hold it in my hands, it isn't a milestone". (3) A test document--describe the nature of testing and any test resources needed. (4) An internal maintenance specification that calls out the code operation in detail. Then you could finally start coding--and coding was subject to code review by an outside (of the project) referee, so you had to be ready to defend the design. And, of course, there were coding standards.
But, incredibly enough, the code probably did what it was supposed to do when released.
From my experience, people not documenting what they did definitely started before smartphones. I guess writing commit messages is hard, boring, and one can generally get away with not doing it, at least for a while - it might cost the author or someone else later, but it's of no immediate value to the author who already has all the information in their head!
Wouldn't it be fair to say that if someone doesn't know or care about proper etiquette for public Git repositories, but they know how to use Git reasonably well, they may in fact make something not impossible, but at least quite hard to find/recover? I'm talking about rewriting history; from this stackoverflow question it appears that GitHub never garbage collects commits that aren't reachable from a branch, but if you do a
git clone/git pull you won't get such commits.
Oh yeah. Remember back in the day how every book and teacher told you to do a flowchart for your code before writing the code, and how almost nobody ever did that?
It's without question hard to write good commit messages, but I'd disagree on the value. Writing a clear, high-level explanation of what you're doing, though difficult, can often really clarify things, for me frequently to the point where I realise I've gone rather wrong in that commit and need to rewrite it. Which is why I often write documentation and/or a rough commit message first: it turns out to force me into doing proper design work, rather than just hacking out code.
I need to pause there because there is no one "proper etiquette" for public Git repositories. What makes for an appropriate level of documentation—including commit messages, documentation files, comments in code and even things like function and variable names—is entirely dependent on the target audience for that documentation, and that can vary vastly. A project with a core of full-time developers and an esoteric application domain might have very clear and efficient communication within the repo for those developers, and yet be near incomprehensible to an outsider not familiar with the application domain, the structure of the code, and the conventions and culture of that core team. That's can be fine if the "secret language" that outsiders must learn to understand the code is something that's helping the development team communicate more clearly and efficiently within the team. The developers have just made a certain choice about the balance between that clear, efficient communication within one group versus acting as a tutorial for outsiders.
*.kicad_{pcb,prl,pro,sch} files in it that mystify software guys really need a detailed explanation of what KiCad is, how to download it, how to read schematics, what components are, an annotation on every pull-up resistor explaining what a pull-up resistor does, and so on?I suspect that there is still a reference somewhere in GitHub; I've added an answer to that StackOverflow question explaining what's going on in more detail.
That's certainly true. I got the impression however that it's fairly universally considered rude to rewrite a branch that other people are using, because of how annoying it is to deal with, although I'm not an expert in collaboration using Git. I suppose with GitHub you don't really know if anyone else is using it - it's not like they're your team members and you can ask them - so I'd probably err on the side of not rewriting, but others may not worry so much and just do it.
I think that making a commit go away permanently is something that is sometimes necessary, e.g. because someone accidentally pushed some private information to GitHub. However, nobody is policing the use of that feature and I wouldn't be surprised if some users did it when they didn't need to but they just didn't care about the impact on others. Someone could remove stuff just because they're a bit embarrassed by a mistake they made. Note that I'm still trying to address part of the original question here - in response to the question below I'm trying to say that it's quite possible there's no record at all of something being removed:
That's certainly a fairly universal convention (and one that I thoroughly agree with—development branches are one of the only areas where I approve of "code ownership"). But keep in mind, this can only happen when you've explicitly given someone else push access to your repo, or someone else has explicitly given you push access to their repo. In the normal course of things, your development branches are in a fork repo owned by you, even though the PR you submit might be in another project.
Per the above, they are your team members, because if you can do this, one of you gave the other access to a repo that you're now sharing.
This can happen in certain circumstances: you had fetched a copy of those commits before they were removed because, e.g., someone rewrote the main branch and you saw this because you have copies of both the old and new versions of the main branch. But this is not the normal way things are "removed" in a Git-controlled repo, and so I think not what the OP was talking about.
That's the kind of question that can be answered only by looking at the existing project and the changes you've made. Without even such basic information such as whether it's your own project that you're updating or you're proposing changes to someone else's project, there's no place to start.
For that the obvious thing to do would be just to put the updated firmware on the main branch of your repo. You could either replace the old firmware (which will still be available in previous commits) or, if the older firmware is still a useful alternative, put both into the repo in separate subdirectories.