Hacker News Reader

Comment by Polylactic_acid | Hacker News Reader

I don't mind the visual style of sourcehut but I find the UI very confusing. I just went to do a few common tasks and I was struggling. First I went to find a list of branches and I had to click through every tab until I landed on "refs" that had it. What does refs mean? I assume its some internal git terminology but why not just call the tab branches. I then went to find out where I could submit a PR/MR and I couldn't find any such feature. I also couldn't find a list of bugs or how to open one.

I'm not really sure what case you would want to use this over GitLab/Gitea which work very well for basically every use case. Especially when you consider that you are driving away potential contributors by using this.

View on HN

The refs tab is not called branches because it is for references. We use git terminology deliberately, because it is a tool for git, and you should not be afraid of understanding your tools. On hg.sr.ht, for example, it's named differently, because Mercurial is designed differently and has different terminology.

SourceHut is not GitHub/GitLab/Gitea, and you would be ill-advised to treat it as such. I have no intention of building yet another GitHub clone. If you insist on everything having the same workflow, then what utility is there in different tools? Be prepared to challenge your preconceptions when learning how to use SourceHut. The documentation is thorough and has lots of tutorials to help you along the way:

https://man.sr.ht/

There are no pull requests or merge requests. We use email, which is how Git was designed to be used. This tutorial will get you started:

https://git-send-email.io

If you just want a GitHub clone, use a GitHub clone. Don't evaluate SourceHut by that critera.

> We use git terminology deliberately, because it is a tool for git, and you should not be afraid of understanding your tools.

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.

> There are no pull requests or merge requests.

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

>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-...

> 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.

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.

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!

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

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.

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

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.

Thank you for that attitude.

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".

> 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.

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.

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

> 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/

> 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.

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.

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 :).

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.

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?

Out of curiosity: what do you think of the attempts to create something better than emails for communication? Maybe easier to host without getting harassed by big corps anti-spam systems. Maybe with cryptography being easier and less error prone to use.

What do you think of something like Matrix?

> There are no pull requests or merge requests. We use email, which is how Git was designed to be used.

I get that some people really like mailing lists, and I am aware of the shortcomings of the pull/merge request model. But I've never really contributed to a project that used mailing lists, and there are some problems I see with mailing list. Perhaps it's just my lack of familiarity with the workflow, but these are some advantages I think the github-style flow has:

- Ability to subscribe to individual pull requests. Many mailing lists are very high volume, and afaik, it isn't possible to subscribe to individual threads. Yes I could subscribe to the list and set up filters, but that is more difficult than subscribing to individual pull requests in github, and getting the filters right could be tricky.

- Ability to search by tags/labels

- Automatic linking between related issues and pull requests (with backreferences)

- The request is itself a git branch, which makes it easy to compare both the current state of the request to master, as well as see incremental changes to the request as individual commits. I'm not sure how to accomplish that in a mailing list.

- Highlighting changes in the diff (source hut actually does this)

I'd be curious to know if proponents of the mailing list flow have anything to accomplish functionality similar to these. Or if there are any tools or tricks they use to make dealing with patch requests in email easier.

TBH it sounds to me that you just need a better email client ?

Like... that's the program that handles everything that you mentioned.

Well, an email client isn't a tool just for developing - it's a generic tool that has a lot of use cases. I don't think one should sacrifice features to get diff highlights or filtering PRs, nor should a generic email client try to implement out-of-the-box SourceHut filtering functionality.

Yes, one can use specific filters to accomplish subscribing to a particular PR, but that's complex, and when I'm using a generic email client I can't think of how it can not be complex.

Nothing is stopping you from using more than one email client.

then you would need to configure filters across multiple email clients, which only makes the filter problem worse.

I use two, with very different filters. Since I use them for different things there’s not much overlap between the configurations. The total volume of conf is probably larger than if I’d used one client only, but the user experience is also a lot better (for me) since I can use the best tool in more cases.

The best solution to email filtering is not receiving irrelevant emails in the first place. It’s always funny seeing people bending over backwards to justify terrible inconveniences they’re merely used to.

Plus, an email program that handles automatic cross referencing of tickets and commits? Where can I find that “better email client”?

aerc [1] supports arbitrary content filters (programs invoked when showing a message body). These are used for quote and diff highlighting. It would be nice to write a filter that auto-links tickets and commits depending on the List-Id.

[1]: https://aerc-mail.org/

Automatic cross referencing is more than linkifying ticket ids and commit hashes. Issues, PRs and commits elsewhere that reference an issue/PR show up automatically on its page (think pingbacks in blogging), which apparently doesn’t fit into the mailing list model at all.

Edit: Forgot to mention, even

> It would be nice to write a filter that auto-links tickets and commits depending on the List-Id.

is not possible with sr.ht, due to non-1-1 relationship between mailing list and repository/tracker.

Sure. What is that better email client? I don't mean to imply there isn't one, I'm genuinely curious what you email client you think has these features.

Many of these features can be implemented in lists.sr.ht.

lists.sr.ht already has support for threads and diff highlighting. Example thread: https://lists.sr.ht/~emersion/public-inbox/patches/7077

Quick drive-by response:

>Ability to subscribe to individual pull requests

>Automatic linking between related issues and pull requests (with backreferences)

Both are planned

>The request is itself a git branch, which makes it easy to compare both the current state of the request to master, as well as see incremental changes to the request as individual commits. I'm not sure how to accomplish that in a mailing list.

Not planned, but you can pretty trivially do this yourself. Just git checkout -b test-branch before applying the commits locally.

>Ability to search by tags/labels

Already there, kind of. You can search by the patch prefix, which is generally used to indicate the subproject. This is also supported outright on tickets, for which it's arguably a lot more useful.

> Just git checkout -b test-branch before applying the commits locally.

I guess that works, but it is a few more steps than clicking on a link. And if you are actively working on the project, it means you have to either switch branches or make a new workspace.

> We use email, which is how Git was designed to be used.

> If you insist on everything having the same workflow, then what utility is there in different tools?

I'll admit many if not most git users have only ever tasted the GitHub workflow, but there are also many who have experienced the old school email workflow and the GitHub workflow and legitimately prefer the latter. Two major considerations:

1. A lot of value-add around pull requests, both in terms of organization/filtering and lifecycle features (inline comments/reviews, CI/CD integration, policy enforcement, merging from web interface, etc.). I planned to go into details here and actually wrote quite a few bullet points before realizing I can't do this topic justice without spending a lot of time to produce a huge wall of text, so please excuse me for the lack of details. (Note: not saying CI/CD integration is impossible with the email workflow, but it doesn't seem possible on sr.ht at the moment without manually pushing someone else's patch to a branch of yours -- correct me, and other implementations I have seen are nowhere as streamlined as those provided by GitHub and clones.)

2. Difficulties around git-send-email and git-am. git-send-email.io only covers half of the equation and coverage isn't complete (e.g. In-Reply-To is not covered). Even the incomplete coverage highlights the complexity. Now what about the git-am side of the equation? How do I fish out a patch from my email client, any email client? How do I figure out which commit to apply the patch on top? Then there's the branching and git-am dance. Maybe it could be streamlined if you use some sort of hacker's mail client with ninja plugins, but you'll have a hard time convincing most people to give up their preferred mail client just because it's not git-friendly. The PR workflow, on the other hand, stays within the boundaries of push/fetch/pull/checkout, the basic operations required for working with any git remote and core competency of any git client (if you choose to use one); no ninja mail client required. hub(1) makes it even easier.

I don't think "how Git was designed to be used" is a strong defense, Linus isn't almighty and what he originally designed could be improved.

I can understand not being a GitHub clone, but when flexibility is a stated goal (I'm sort of reading between the lines, correct me if I'm wrong) maybe it doesn't hurt to support multiple workflows (a lot of work of course). Rejecting a popular and arguably superior (for many if not most git users) workflow means leaving a lot of potential users on the table, which is in itself okay depending on your goal.

>inline comments/reviews

>CI/CD integration

>merging from web interface

All of this is possible and planned for or already working on SourceHut. Remember, SourceHut is an alpha - don't write it off just yet because it's not entirely complete.

>Difficulties around git-send-email and git-am. git-send-email.io only covers half of the equation and coverage isn't complete

I intend to follow-up with git-am.io at some point, for what it's worth. And I disagree that it's incomplete: it just encourages a workflow which doesn't use In-Reply-To. It covers follow-up patches without it.

>you'll have a hard time convincing most people to give up their preferred mail client just because it's not git-friendly

My response to this is (1) you can use multiple email clients for different reasons, you don't need to give up your current one; and (2) you don't need a special email client to apply patches from lists.sr.ht, every patchset page has a little CLI command you can copy+run to fetch the patch with curl and feed it to git am.

>Rejecting a popular and arguably superior (for many if not most git users) workflow means leaving a lot of potential users on the table

Popular, yes. Superior, definitely not. But leaving that aside: I am okay with leaving potential users on the table. I'm not maximizing the possible userbase of SourceHut. I'm building a platform that embodies my development principles, for people who find those principles worthwhile.

Good to hear all the planned features in this reply and https://news.ycombinator.com/item?id=23041522. One small clarification: re: inline comments/reviews, what I had in mind was all reviews aggregated on a single page, not scattered and obsoleted by each patch version, which means comments are basically lost if not immediately addressed.

Anyway, it seems to me that once you have all these planned features, the workflow would inch towards the Phabricator workflow, and to a lesser extent the GitHub workflow. The only major differentiator would be that you use emails to send in patches instead of using a branch. The actual code review activity would center around the web interface instead of the mailing list. That would mean (if my interpretations are correct) we disagree to a much smaller extent than I thought, but that would also mean your workflow is actually pretty different from “how git was designed to be used”, which I interpret as the mailing list-centric workflow of lkml (as I understand it; I’m not involved) and other old school projects I have participated in.

Re mail clients:

> (1) you can use multiple email clients for different reasons, you don't need to give up your current one;

It’s possible, but not pleasant. Each client needs to be configured so that mail intended for the other doesn’t clutter it up (not only inbox, but also search, archive, etc.). Usually people already use two or more mail clients to begin with (pc, mobile), so, more configurations.

> (2) you don't need a special email client to apply patches from lists.sr.ht, every patchset page has a little CLI command you can copy+run to fetch the patch with curl and feed it to git am.

Yeah I’m aware of this, but this just brings back the point that you’re using emails but then not really using emails...

>Yeah I’m aware of this, but this just brings back the point that you’re using emails but then not really using emails...

_I_ like using emails. But the point of tools like that are so that people who don't like using emails can use other tools instead, and seamlessly collaborate with people who prefer to use emails.

What I found confusing is that after finding the source code page for a project, I couldn't figure out where to go navigate to the related bug tracker, mailing list, wiki, etc. It looks like the project hub now has project pages that help with that, but the individual pages don't seem to have backlinks to the project that contains them (or at least if they do, I can't find them). But it's still a work in progress, so hopefully that will come in due time.

Reply on news.ycombinator.com