[ddevault]

>I know git internals enough to know what a ‘ref’ is, but IMHO it’s a word that’s pretty hard for an average git user to know. I would suggest at least having a tooltip with some text like ‘Git references: branches, tags, etc...’ so that beginners can understand what it‘s used for.

In general this is against our principles. We prefer to teach people how to use powerful tools rather than make less powerful tools that are easier to use. I don't believe that users are not capable of learning new things. In this particular case, this is the first time anyone has commented on "refs" being difficult to understand in the 1.5 years that SourceHut has been around.

>If I remember correctly, I thought that a way to submit patches through a web UI was being developed... Is it still true?

Yeah, this is still true, and somewhat implemented now. The large blue button on the repo summary page can clone the repo to your account, and then be used to interactively prepare a patchset to send to the mailing list. I'm not sure how Polylactic_acid missed it, actually, unless they don't have an account. The UI only works for account holders, though the big button is replaced with instructions on how to contribute by email if you're logged out.

There's a video of the process here:

https://sourcehut.org/blog/2019-10-15-whats-cooking-october-...

[pcr910303]

> In general this is against our principles. We prefer to teach people how to use powerful tools rather than make less powerful tools that are easier to use.

IMHO progressive disclosure is important, because if you want something to be widespread, beginners should be able to use SourceHut with little guidance.

> I don't believe that users are not capable of learning new things.

Well, for the users to learn git terminology, one has to start using git — and one of the biggest reasons is to start using git is to clone popular projects or cooperating between different people. If SourceHut is hostile (I’m not saying that it’s currently hostile, but I think it may improve) for people who don’t what a ‘ref’ is, people have to start using GitHub — and the newcomers of SourceHut becomes the very small portion of people who are already an ‘git expert’ and is interested in emailing patches.

If SourceHut wants to make the email patches/other workflows that SourceHut encourages mainstream, I think it’s crucial for git newcomers to be able to use it. It’s a losing game otherwise.

[ddevault]

But your suggestion relies on them knowing what "branches" are - an equally tenuous proposition for a new programmer, I think. Recall that at one point, you didn't know how to use GitHub, either. Pull requests? Cloning? What do these words mean, out of context? New users on GitHub struggle a lot, too, something I know from firsthand experience dealing with new programmers on my GitHub projects all the time.

I would prefer to solve these problems by fostering a culture of mentorship, and being responsive to questions. This is what I do on GitHub, too.

[mikekchar]

Just to support your philosophy a little bit, most git users are very surprised to learn that a "branch" is a single commit. When they need to do something where this distinction matters, in my experience they are usually stymied. Using a precise model where it doesn't sweep the details under the carpet is good for me. However, I suspect that it will limit adoption to a certain extent. Pretending that something is the way you wish it to be is pretty common in the world ;-) Refusing to use tools that show you truths that you do not wish to acknowledge is similarly common, I think. Still I appreciate the precision and if you are targeting users like me, I certainly won't complain!

[umvi]

A branch is more accurately a text pointer pointing to a single commit

[TeMPOraL]

And this is a crucial point. To understand git, you need to understand data structures strung from pointers. Branch then being a [pointer to a] single commit makes perfect sense, just like a linked list being a pointer to the first element makes perfect sense.

[rswail]

You could even call it a "reference", or a "ref" for short :)

[pcr910303]

I agree with that PRs are a foreign concept — but branchs and cloning is text that almost always appear on introductory git tutorials which make them friendlier than the other terms.

I actually just realized that if SourceHut has a site (like git-send-email.io) that explains git that uses the terms ‘ref’ and etc... (so that a git newcomer can build a proper fit mental model), this problem goes away. Not sure if explaining it easily would be possible though.

[mb7733]

I agree with all of this and it's worth pointing out that unlike "ref" which some posters are claiming is too obscure, "pull request" is not even a term within git itself.

As someone who was quite familiar with git before using GitHub, GH's use of that term was the only confusing thing. (It is only not a request for others to `pull` your branch to inspect the changes, it's also a request to merge it into some other branch.)

A term like "ref" is at least part of the standard git terminology, and used in important commands that everyone should know like "reflog".

[toohotatopic]

Thank you for that attitude.

[jckzlg]

> In general this is against our principles. We prefer to teach people how to use powerful tools rather than make less powerful tools that are easier to use.

I agree deeply with the ethos this statement represents. It's hard for me to formulate at the moment what I think this "ethos" is exactly, but I think it's really important. I'll try to explain by example. I think we should favor manpages over Stack Overflow, documentation over Google, composable CLI tools over monolithic IDEs, etc. I think that every engineer on a team should have read the most popular O'Reilly book (or some equivalent) for each of the tools the team works with. Of course, these "rules" are not commandments and we should always strive to be prudent.

Sometimes I'm accused of being cranky for these sorts of opinions, and I guess I might be, but I also see so much time and money wasted because nobody in an organization understands basic tools like SSH or how to use systemd.

The other day there was a developer tool on the front page of hacker news that lets you "run apps in the cloud from the comfort of your own editor". This is in my opinion a sign of the techpocalypse.

Edit: s/UPPERCASE/italics/

[TeMPOraL]

I generally agree with you. Especially strongly on the point about books.

It is my observation that, just as much as Stack Overflow and various on-line cheatsheets are replacing man pages (which is unfortunate), man pages are replacing info pages. By that I mean they aren't thorough enough. My eyes opened to that point when I started browsing M-x info in my Emacs, and run across documentation of non-Emacs things. Info pages tend to be more like a book than a short manual. And it's great, since if you're going to be using a tool semi-regularly, going through a book explaining it is a boost in learning time and scope.

And as a more general point: I miss the times when software shipped with book-sized manuals.

> run apps in the cloud from the comfort of your own editor". This is in my opinion a sign of the techpocalypse

I guess it depends on where you compose. The above goes against Unix philosophy, but not necessarily against Emacs philosophy. I.e. I consider Emacs as a 2D interface to composable applications (vs. 1D interface a command line is). So a bit of Elisp that implements a cloud API provides a piece that can be composed with just about every other piece of Elisp in Emacs, yielding a solution that's both composable and convenient :).

[jckzlg]

The issue here in my opinion is not that someone would “run apps in the cloud from your editor”, it’s that a software engineer would need or want an entire SaaS product for such a trivial task.

[thayne]

> I think we should favor manpages over Stack Overflow, documentation over Google

these are not really comparable things. I definitely don't think that Stack Overflow should replace man pages, but I still find Stack Overflow valuable. It's value is in finding how someone else solved a problem similar to the one you had, or where you go to ask other developers for help when the your attempt at finding the needed information in the documentation has failed.

[jckzlg]

I almost entirely agree, and I think the word "favor" wasn't the best choice. My opinion is that many developers will often consult Google or Stack Overflow before consulting a manpage or documentation or will only briefly consult documentation before a Google search. I'm definitely guilty of this, especially when I'm under a tight deadline, but I think it's a behavior that should be avoided when possible. Navigating documentation and/or manpages forces you to engage with the structure of the tool you're using, Google and Stack Overflow do not.

[rswail]

The issue is that when we hire skilled craftsmen or engineers, we expect them to be familiar with and capable of using the tools of their craft.

You wouldn't hire a carpenter who didn't know how to use a hammer, why do we expect so called "software engineers" to be handheld through using a basic tool like git, which is entirely based on simple structures like a DAG, immutable hashes and pointers?

[Aeolun]

> In this particular case, this is the first time anyone has commented on "refs" being difficult to understand in the 1.5 years that SourceHut has been around.

To be fair, when I tried sourcehut the first time around, I did go ‘wtf’ when I saw branches being called refs.

I didn’t end up using it though, so I’m probably not the target market.

I do like the reasoning behind the hub released now though, so maybe I’ll try again.

[vnorilo]

I use hg by choice and git when needed. The git interface feels confusing to me, but after learning the data model (enough to construct commits with the github data api) it suddenly seems a lot simpler, which I feel is a good reason to grok what "ref" actually means.

[Aeolun]

That is true, but I’m not sure if it’s a good reason to use ‘ref’ in daily conversation.