Hello there :D
I honestly don't know if I'm missing something, but I find contributing,
building and deploying Sourcehut quite confusing.
For the last few weeks I have been trying to get to know the Sourcehut
codebase more to try and contribute some patches but I found myself lost
in the labirynth of files and little to no documentation about the code
so I thought I would mess with it locally in a docker container but
found little to nothing about building and running from source except
using pre-built packages for alpine linux which I am not really familiar
with.
While all of these problems can be solved with a little time and effort,
I don't think something as simple as sending a patch or building from
source should be this hard. I'm slowly starting to get the hang of it,
but new and less experienced people will find it even harder to deploy
or contribute to Sourcehut.
Any thoughts?
Funny you mention this. Just yesterday I was considering starting a
live-streaming series "hacking on Sourcehut" (I suck at names).
Currently I stream from-scratch protocol dev in Go [1].
It would involve contribution - submitting patches etc. - and of
course reading a lot of Sourcehut's documentation. Hopefully a bit of
Sourcehut and alternative (i.e. not "that pull request site")
development workflow signal boosting too ;) Perhaps a hackathon
encouraging others to contribute?
[1]: https://git.olowe.co/streaming
Monti <contact@montidaproot.xyz> writes:
> It's definitely something, but as much as I hate to point it out, I don't see where it addresses > the> problem I mentioned here
A few people tried streamlining the bootstrap process to reduce the time to get to /actually/ write
a patch but nothing official from Sourcehut and nothing actively maintained.
Just mentioning the a few hits I see from a quick search:
https://sr.ht/~ulyc/sourcehut-docker/https://sr.ht/~emersion/sr.ht-container-compose/
Hope this helps, at least as a starting point.
On 7/11/24 15:00, jman wrote:
> A few people tried streamlining the bootstrap process to reduce the time > to get to /actually/ write a patch but nothing official from Sourcehut > and nothing actively maintained.> > Just mentioning the a few hits I see from a quick search:> https://sr.ht/~ulyc/sourcehut-docker/> https://sr.ht/~emersion/sr.ht-container-compose/> > Hope this helps, at least as a starting point.
Hm... this at least partially solves the deployment problem, but it
still leaves us with no documentation at all about building from source
or deploying outside of Alpine Linux, for example to test patches before
sending them
These are the only resources that exist right now:
* https://man.sr.ht/installation.md
* https://man.sr.ht/configuration.md
And most importantly:
* https://man.sr.ht/hacking.md
I've followed them successfully, though they are incomplete and not extremely intuitive. The best thing to do would probably be to follow the instructions yourself and send patches to improve the documentation where this is needed. This may be especially helpful to others if you want to try this on another distro than Alpine Linux. It's definitely not the smoothest process right now, though.
On 7/11/24 17:21, Vlad-Stefan Harbuz wrote:
> These are the only resources that exist right now:> > * https://man.sr.ht/installation.md> * https://man.sr.ht/configuration.md> > And most importantly:> > * https://man.sr.ht/hacking.md> > I've followed them successfully, though they are incomplete and not extremely intuitive. The best thing to do would probably be to follow the instructions yourself and send patches to improve the documentation where this is needed. This may be especially helpful to others if you want to try this on another distro than Alpine Linux. It's definitely not the smoothest process right now, though.
Ah... So in the end I did end up missing something.
Well, I took a look at https://man.sr.ht/installation.md and noticed
that the hacking section is mentioned, but in a rather inconvenient way,
as most users will probably end up overlooking it as well.
I guess at least I have a place to send a patch, since to me it's a
small design flaw that it's not more clearly stated, as I was really
looking for a section called "contributing" or something similar.
On Thu, Jul 11, 2024 at 07:38:49PM +0200, Monti wrote:
> On 7/11/24 17:21, Vlad-Stefan Harbuz wrote:> > These are the only resources that exist right now:> > > > * https://man.sr.ht/installation.md> > * https://man.sr.ht/configuration.md> > > > And most importantly:> > > > * https://man.sr.ht/hacking.md> > > > I've followed them successfully, though they are incomplete and not extremely intuitive. The best thing to do would probably be to follow the instructions yourself and send patches to improve the documentation where this is needed. This may be especially helpful to others if you want to try this on another distro than Alpine Linux. It's definitely not the smoothest process right now, though.> > Ah... So in the end I did end up missing something.> > Well, I took a look at https://man.sr.ht/installation.md and noticed that> the hacking section is mentioned, but in a rather inconvenient way, as most> users will probably end up overlooking it as well.
It's right there in the second sentence, first sentence of second
paragraph. How can this be inconvenient?
On 7/12/24 06:18, Rene Kita wrote:
> On Thu, Jul 11, 2024 at 07:38:49PM +0200, Monti wrote:>> On 7/11/24 17:21, Vlad-Stefan Harbuz wrote:>>> These are the only resources that exist right now:>>>>>> * https://man.sr.ht/installation.md>>> * https://man.sr.ht/configuration.md>>>>>> And most importantly:>>>>>> * https://man.sr.ht/hacking.md>>>>>> I've followed them successfully, though they are incomplete and not extremely intuitive. The best thing to do would probably be to follow the instructions yourself and send patches to improve the documentation where this is needed. This may be especially helpful to others if you want to try this on another distro than Alpine Linux. It's definitely not the smoothest process right now, though.>>>> Ah... So in the end I did end up missing something.>>>> Well, I took a look at https://man.sr.ht/installation.md and noticed that>> the hacking section is mentioned, but in a rather inconvenient way, as most>> users will probably end up overlooking it as well.> > It's right there in the second sentence, first sentence of second> paragraph. How can this be inconvenient?
All important aspects should be in places where the user will definitely
look, in this case the table of contents, because of the layout of
sourcehut man pages, which looks like this:
```
[Table of Contents].
[Introduction]
[Sections of the man page].
```
Most users will simply skip the introduction, as they will jump straight
to the part of the man page they are interested in via the table of
contents, making the `hacking' page hard to find.
The simplest fix would be to put the introduction in its own section and
do the same for `hacking', but renaming it to "developing" or
"contributing" as the original title is another design flaw that I do
not think I need to explain, as anyone who will think for at least 10
seconds will figure that out.
On Fri, Jul 12, 2024 at 06:13:27PM +0200, Monti wrote:
[...]
> > > Well, I took a look at https://man.sr.ht/installation.md and noticed that> > > the hacking section is mentioned, but in a rather inconvenient way, as most> > > users will probably end up overlooking it as well.> > > > It's right there in the second sentence, first sentence of second> > paragraph. How can this be inconvenient?> > > All important aspects should be in places where the user will definitely> look, in this case the table of contents, because of the layout of sourcehut> man pages, which looks like this:> > ```> [Table of Contents].> [Introduction]> [Sections of the man page].> ```> > Most users will simply skip the introduction, as they will jump straight to> the part of the man page they are interested in via the table of contents,> making the `hacking' page hard to find.> > The simplest fix would be to put the introduction in its own section and do> the same for `hacking', but renaming it to "developing" or "contributing"
Having a file called HACKING or hacking is a traditional way to provide
information to people interesting in contributing to open source
projects, see e.g. the Linux kernel.
> as the original title is another design flaw that I do not think I> need to explain, as anyone who will think for at least 10 seconds will> figure that out.
I disagree and I don't think this is the appropriate tone for a
technical discussion. I certainly have thought for at least 10 seconds
before writing my first mail.
On 7/12/24 18:36, Rene Kita wrote:
> On Fri, Jul 12, 2024 at 06:13:27PM +0200, Monti wrote:
> [...]
>
>>>> Well, I took a look at https://man.sr.ht/installation.md and
noticed that
>>>> the hacking section is mentioned, but in a rather inconvenient
way, as most
>>>> users will probably end up overlooking it as well.
>>>
>>> It's right there in the second sentence, first sentence of second
>>> paragraph. How can this be inconvenient?
>>
>>
>> All important aspects should be in places where the user will definitely
>> look, in this case the table of contents, because of the layout of
sourcehut
>> man pages, which looks like this:
>>
>> ```
>> [Table of Contents].
>> [Introduction]
>> [Sections of the man page].
>> ```
>>
>> Most users will simply skip the introduction, as they will jump
straight to
>> the part of the man page they are interested in via the table of
contents,
>> making the `hacking' page hard to find.
>>
>> The simplest fix would be to put the introduction in its own section
and do
>> the same for `hacking', but renaming it to "developing" or
"contributing"
>
> Having a file called HACKING or hacking is a traditional way to provide
> information to people interesting in contributing to open source
> projects, see e.g. the Linux kernel.
>
>> as the original title is another design flaw that I do not think I
>> need to explain, as anyone who will think for at least 10 seconds will
>> figure that out.
>
> I disagree and I don't think this is the appropriate tone for a
> technical discussion. I certainly have thought for at least 10 seconds
> before writing my first mail.
> I disagree and I don't think this is the appropriate tone for a
> technical discussion. I certainly have thought for at least 10 seconds
> before writing my first mail.
I'm sorry if that offended you or anyone else in this discussion,
because that wasn't my intention, and it was about thinking about it
from a design and user friendliness perspective
Again, I'm sorry for making it sound that way, it's a mistake on my side.
> Having a file called HACKING or hacking is a traditional way to provide> information to people interesting in contributing to open source> projects, see e.g. the Linux kernel.
This would be a traditional way for very technical users who are deeply
familiar with the Linux kernel contribution workflow, I think Sourcehut
should also consider less experienced users coming from git forges like
Gitlab, Github or Codeberg (forgejo).
Personally, I'm very used to contributing through pull/merge requests,
but that doesn't mean I'm not open to discovering and maybe even
changing my workflow.
On Fri, Jul 12, 2024 at 07:29:55PM +0200, Monti wrote:
> On 7/12/24 18:36, Rene Kita wrote:> > On Fri, Jul 12, 2024 at 06:13:27PM +0200, Monti wrote:> > [...]> >> >>>> Well, I took a look at https://man.sr.ht/installation.md and noticed> that> >>>> the hacking section is mentioned, but in a rather inconvenient way, as> most> >>>> users will probably end up overlooking it as well.> >>>> >>> It's right there in the second sentence, first sentence of second> >>> paragraph. How can this be inconvenient?> >>> >>> >> All important aspects should be in places where the user will definitely> >> look, in this case the table of contents, because of the layout of> sourcehut> >> man pages, which looks like this:> >>> >> ```> >> [Table of Contents].> >> [Introduction]> >> [Sections of the man page].> >> ```> >>> >> Most users will simply skip the introduction, as they will jump straight> to> >> the part of the man page they are interested in via the table of> contents,> >> making the `hacking' page hard to find.> >>> >> The simplest fix would be to put the introduction in its own section and> do> >> the same for `hacking', but renaming it to "developing" or "contributing"> >> > Having a file called HACKING or hacking is a traditional way to provide> > information to people interesting in contributing to open source> > projects, see e.g. the Linux kernel.> >> >> as the original title is another design flaw that I do not think I> >> need to explain, as anyone who will think for at least 10 seconds will> >> figure that out.> >> > I disagree and I don't think this is the appropriate tone for a> > technical discussion. I certainly have thought for at least 10 seconds> > before writing my first mail.> > > > I disagree and I don't think this is the appropriate tone for a> > technical discussion. I certainly have thought for at least 10 seconds> > before writing my first mail.> > I'm sorry if that offended you or anyone else in this discussion, because> that wasn't my intention, and it was about thinking about it from a design> and user friendliness perspective> Again, I'm sorry for making it sound that way, it's a mistake on my side.
Don't worry, just wanted to point this out.
> > Having a file called HACKING or hacking is a traditional way to provide> > information to people interesting in contributing to open source> > projects, see e.g. the Linux kernel.> > This would be a traditional way for very technical users who are deeply> familiar with the Linux kernel contribution workflow, I think Sourcehut> should also consider less experienced users coming from git forges like> Gitlab, Github or Codeberg (forgejo).> > Personally, I'm very used to contributing through pull/merge requests, but> that doesn't mean I'm not open to discovering and maybe even changing my> workflow.
Renaming it to contributing because hacking is old fashioned is an
argument - but this is a discussion I don't want to be part in.
As you said and which I can confirm from experience, user will not read
it anyways. I think as it is now, with a link right at the beginning of
the content any user who actually reads it has a good chance to
understand what it's about - no matter if it's called hacking or
contributing.
What about adding a section called 'Contributing' which is also listed
in the ToC and from there we link to 'Hacking'? That way users who skim
the ToC and/or are not familiar with the term hacking in this context
would find the correct document *and* learn about that grey-beard term?
Дана 24/07/12 06:13PM, Monti написа:
> The simplest fix would be to put the introduction in its own section and do> the same for `hacking', but renaming it to "developing" or "contributing" as> the original title is another design flaw that I do not think I need to> explain, as anyone who will think for at least 10 seconds will figure that> out.
If you haven't already, I strongly suggest you read this:
https://stallman.org/articles/on-hacking.html
it is the rationale behind this terminology, and one of the hallmarks
of Free Software culture.
On 7/12/24 19:53, Rene Kita wrote:
On Fri, Jul 12, 2024 at 07:29:55PM +0200, Monti wrote:
>> On 7/12/24 18:36, Rene Kita wrote:>>> On Fri, Jul 12, 2024 at 06:13:27PM +0200, Monti wrote:>>> [...]>>>>>>>>> Well, I took a look at https://man.sr.ht/installation.md and noticed>> that>>>>>> the hacking section is mentioned, but in a rather inconvenient way, as>> most>>>>>> users will probably end up overlooking it as well.>>>>>>>>>> It's right there in the second sentence, first sentence of second>>>>> paragraph. How can this be inconvenient?>>>>>>>>>>>> All important aspects should be in places where the user will definitely>>>> look, in this case the table of contents, because of the layout of>> sourcehut>>>> man pages, which looks like this:>>>>>>>> ```>>>> [Table of Contents].>>>> [Introduction]>>>> [Sections of the man page].>>>> ```>>>>>>>> Most users will simply skip the introduction, as they will jump straight>> to>>>> the part of the man page they are interested in via the table of>> contents,>>>> making the `hacking' page hard to find.>>>>>>>> The simplest fix would be to put the introduction in its own section and>> do>>>> the same for `hacking', but renaming it to "developing" or "contributing">>>>>> Having a file called HACKING or hacking is a traditional way to provide>>> information to people interesting in contributing to open source>>> projects, see e.g. the Linux kernel.>>>>>>> as the original title is another design flaw that I do not think I>>>> need to explain, as anyone who will think for at least 10 seconds will>>>> figure that out.>>>>>> I disagree and I don't think this is the appropriate tone for a>>> technical discussion. I certainly have thought for at least 10 seconds>>> before writing my first mail.>>>>>>> I disagree and I don't think this is the appropriate tone for a>>> technical discussion. I certainly have thought for at least 10 seconds>>> before writing my first mail.>>>> I'm sorry if that offended you or anyone else in this discussion, because>> that wasn't my intention, and it was about thinking about it from a design>> and user friendliness perspective>> Again, I'm sorry for making it sound that way, it's a mistake on my side.> > Don't worry, just wanted to point this out.> >>> Having a file called HACKING or hacking is a traditional way to provide>>> information to people interesting in contributing to open source>>> projects, see e.g. the Linux kernel.>>>> This would be a traditional way for very technical users who are deeply>> familiar with the Linux kernel contribution workflow, I think Sourcehut>> should also consider less experienced users coming from git forges like>> Gitlab, Github or Codeberg (forgejo).>>>> Personally, I'm very used to contributing through pull/merge requests, but>> that doesn't mean I'm not open to discovering and maybe even changing my>> workflow.> > Renaming it to contributing because hacking is old fashioned is an> argument - but this is a discussion I don't want to be part in.> > As you said and which I can confirm from experience, user will not read> it anyways. I think as it is now, with a link right at the beginning of> the content any user who actually reads it has a good chance to> understand what it's about - no matter if it's called hacking or> contributing.> > What about adding a section called 'Contributing' which is also listed> in the ToC and from there we link to 'Hacking'? That way users who skim> the ToC and/or are not familiar with the term hacking in this context> would find the correct document *and* learn about that grey-beard term?> What about adding a section called 'Contributing' which is also listed> in the ToC and from there we link to 'Hacking'? That way users who skim> the ToC and/or are not familiar with the term hacking in this context> would find the correct document *and* learn about that grey-beard term?
That would definitely be a nice compromise here, a bit redundant but
still better than nothing!
But if that's a compromise we're going to take, it would also be good to
explain the terminology for people who want to go a bit deeper.
Maybe even a dedicated page explaining the terminology of hacking or,
although it might be a bit controversial for some, a link to Stallman's
article that our Russian buddy sent above or just a quick tl;dr of it to
get the user on the right track?
Of course it's just a suggestion but I'm trying to think of every
possible scenario here soooo :b
Дана 24/07/12 07:29PM, Monti написа:
> This would be a traditional way for very technical users who are deeply> familiar with the Linux kernel contribution workflow, I think Sourcehut> should also consider less experienced users coming from git forges like> Gitlab, Github or Codeberg (forgejo).
The motto of Sourcehut is "The Hacker's Forge". Its appeal is precisely
in its difference from mainstream source hosting sites, mainly Github.
It is geared towards a non-mainstream, alternative audience.
> Personally, I'm very used to contributing through pull/merge requests, but> that doesn't mean I'm not open to discovering and maybe even changing my> workflow.
There are plenty of Github clones which are not Github for that.