Hello! I wanted to start a discussion on how to go about refactoring
man.sr.ht so that it piggybacks off of scm.sr.ht functionality.
Has anybody looked-into or already started working on this?

Not 100% familiar with all of sourcehut's facets, so I'll probably be
missing a bit of vital information here and there.

The obvious benefits to doing this work:

- Less redudancy/duplication.
- All the same management options on git, hg, etc. can be used
  (addresses https://todo.sr.ht/~sircmpwn/man.sr.ht/21, for example).

Should be a small-ish refactor, most of the wiki functionality would
stay the same, we only open-up doors to the management options that
scm.sr.ht provides.

I also noticed this ticket: https://todo.sr.ht/~sircmpwn/man.sr.ht/25.

@ddevault, was wondering what you had in mind with this and how it
would apply in this case?

As far as I can see, man.sr.ht could really work off-of any of the
scm.sr.ht frontends (as opposed to being a frontend itself), although
I'm not too sure how that would work.

Thanks!

Ryan

On 2019-03-05 , Ryan Chan wrote:
> I also noticed this ticket: https://todo.sr.ht/~sircmpwn/man.sr.ht/25.
> 
> @ddevault, was wondering what you had in mind with this and how it
> would apply in this case?

Basically there are two approaches we could take to updating man.sr.ht's
bakcend to be more flexible. They aren't necessarily mutually exclusive,
we could do one now and the other later, but I suspect the other would
just never get done. I'm not too keen on either approach, so if you're
willing to put in the work I'll leave the decision to you.

The easier approach is to refactor man.sr.ht to be based on scm.sr.ht.
It might be able to share a lot of code from git.sr.ht directly. I don't
think abstracting it to support hg as well is going to be feasible. I
think there are few unknowns with this approach.

The harder but more flexible approach starts by fleshing out the
git.sr.ht and hg.sr.ht APIs. Then, when adding a wiki on man.sr.ht, a
git or hg.sr.ht repository is created for that wiki, rather than storing
the repos on man.sr.ht-specific storage. You can use the tools provided
on git/hg.sr.ht for access controls, tree & commit browsing, etc, for
managing your wiki. Then man.sr.ht has two backends, git.sr.ht-based and
hg.sr.ht-based (in all likelihood it would only depend on a small number
of APIs, so this wouldn't be too difficult) which fetchs blobs for
rendering, the latest commit info, and so on.

Thanks for the explanations. I think I might _try_ to go with the
second option since it sounds the most sane to me. I have a couple of
questions about the approach, just want to make sure I'm understanding
everything!

> fleshing out the git.sr.ht and hg.sr.ht APIs

I took a quick look and it looks like there's an API defined in
scm.sr.ht. I'm not very familiar with web API design, did you have some
roadmap/design in mind for it, or is it free for me to take a stab at?

> Then man.sr.ht has two backends, git.sr.ht-based and hg.sr.ht-based
> which fetchs blobs for rendering, the latest commit info, and so on.

Should this introduce special "wiki-type" repos that are picked-up by
man.sr.ht, or would man.sr.ht attempt to render any of the repos in
git/hg.sr.ht?

Would it be ugly to rely on naming convention perhaps? Like if a repo
were to be named "foo-man", then it's accessible via man.sr.ht as a
rendered wiki?

If I'm overcomplicating things, please let me know!

On 2019-03-07 , Ryan Chan wrote:
> I took a quick look and it looks like there's an API defined in
> scm.sr.ht. I'm not very familiar with web API design, did you have some
> roadmap/design in mind for it, or is it free for me to take a stab at?

That API is kind of old and not really supported. I'm going to be
replacing it next week with one based on the newly-established API
conventions:

https://man.sr.ht/api-conventions.md

> Should this introduce special "wiki-type" repos that are picked-up by
> man.sr.ht, or would man.sr.ht attempt to render any of the repos in
> git/hg.sr.ht?

I imagine man.sr.ht would have a table in the database of wikis, which
would each refer to a git.sr.ht or hg.sr.ht repository where the
upstream lives. You'd have to explicitly wire it up by going to
man.sr.ht and specifying which repo you want to create a wiki from
(optionally with an orphaned wiki branch?).

Thanks for the API link. What you said makes sense. Hoping to find some
time within these couple of months to work on this! If it's needed
earlier happy to yield the task to someone else.