[DISCUSSION] Contributing policy for WORG

[DISCUSSION] Contributing policy for WORG

[Ihor Radchenko]

Hi,

Corwin recently noticed that our
https://orgmode.org/worg/worg-about.html page is not very consistent
about whom and how should contribute to WORG.

One part of that page suggests to "Create an account on Sourcehut" and
then push changes freely, while another part suggests going through the
mailing list.

My first reflex was to make things consistent with Org code
contributions, but I recall that Bastien had somewhat different ideas
about WORG contributions - more in line with "free to push changes" and
generally with a spirit of wiki pages (Bastien, correct me if I am
making things up).

Now, thinking about it, I do believe that our general goal should be
making it easier for users to push changes to WORG - easier than
contributing code. And these days creating an account might be easier
for people compared to writing to a mailing list.

Maybe we can simplify things even more by settings something up so that
people can download, edit, and upload WORG pages right from Emacs. For
example, hyperdrive might be used as an alternative to git workflow,
especially if we can cook some kind of setup via a simple M-x <dwm>
command. (see <https://breatheoutbreathe.in/blog/2024-12-16-mirror-worg-to-a-hyperdrive.html>)

WDYT?

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [DISCUSSION] Contributing policy for WORG

[Joseph Turner]

Ihor Radchenko <yantar92@posteo.net> writes:

> Hi,
>
> Corwin recently noticed that our
> https://orgmode.org/worg/worg-about.html page is not very consistent
> about whom and how should contribute to WORG.
>
> One part of that page suggests to "Create an account on Sourcehut" and
> then push changes freely, while another part suggests going through the
> mailing list.
>
> My first reflex was to make things consistent with Org code
> contributions, but I recall that Bastien had somewhat different ideas
> about WORG contributions - more in line with "free to push changes" and
> generally with a spirit of wiki pages (Bastien, correct me if I am
> making things up).
>
> Now, thinking about it, I do believe that our general goal should be
> making it easier for users to push changes to WORG - easier than
> contributing code. And these days creating an account might be easier
> for people compared to writing to a mailing list.
>
> Maybe we can simplify things even more by settings something up so that
> people can download, edit, and upload WORG pages right from Emacs. For
> example, hyperdrive might be used as an alternative to git workflow,
> especially if we can cook some kind of setup via a simple M-x <dwm>
> command. (see <https://breatheoutbreathe.in/blog/2024-12-16-mirror-worg-to-a-hyperdrive.html>)

Thanks for the suggestion!  I imagine such a command would do this:

- install hyperdrive.el
- download and install external gateway program with hyperdrive-install
- open worg hyperdrive.  We could use the hyperdrive I created for the
  blog post hyper://bpb1bq6sdfajw4bok7k9tdmrq153pbwzcyfkrqrfxw3hhihyddhy/
  which is also accessible here:
  https://bpb1bq6sdfajw4bok7k9tdmrq153pbwzcyfkrqrfxw3hhihyddhy.hyper.hypha.coop/
  but I'd suggest the worg maintainers (Ihor) create a new hyperdrive that
  mirrors worg, so that the maintainers control the keys.
- Create a new hyperdrive which mirrors the maintainers' worg hyperdrive.

Then the users edit their hyperdrive and then run a second command to:

- send the URL of the user-created hyperdrive to the maintainers.  How?
  Via email?  hyperdrive.el doesn't currently have a way to "push"
  changes to someone else, only "pull", although this could be added.

For the worg use-case, where all changes need to go back to a central
hub (the worg maintainers and the central git repository), I think
hyperdrive might not help all that much.

Hyperdrive is useful for distributing content like a personal website on
a peer-to-peer network.  The hyperdrive.el Emacs interface adds things
like Org mode link handling, but it doesn't support collaboratively
editing text documents.  [ The hypercore stack does include the
https://github.com/holepunchto/autobase library for creating multiwriter
data structures, but significant effort would be required to create an
auto-merging program on top of hyperdrive.  Here's an example of the
kind of multiwriter programs which can be written with autobase:
https://github.com/hypercore-protocol/p2p-multiwriter-with-autobase ]

From Ihor's direct email to me:

> I imagined that we can simply point users to
> 1. install hyperdrive from ELPA
> 2. M-x magic
> 3. View/edit/add WORG pages locally in Emacs
> 4. <more magic> (involving me adding user hyperdrives to sync with mine,
>    where I can push upstream)
> 5. The edits appear on WORG website

Something like this might work for one-time contributions, but
subsequent contributions would require restarting the process, since
after the maintainers copy the desired changes, there's currently no way
merge the two hyperdrive histories.

Perhaps someone wants to write a CRDT designed to handle Org documents. :)

Joseph

Re: [DISCUSSION] Contributing policy for WORG

[Bastien Guerry]

Hi Joseph, thanks for sharing! I will continue to explore hyperdrive.

Also thinking about Worg again: I don't know what Corwin and Krupal
think, but maybe Worg deserves more maintainers?

Worg should be treated like a real separate product, and maintainers
need to "own" it in order to maintain it efficiently.

2 cts,

-- 
 Bastien Guerry

Re: [DISCUSSION] Contributing policy for WORG

[Corwin Brust]

On Mon, Jan 20, 2025 at 4:27 PM Bastien Guerry <bzg@gnu.org> wrote:
>
> Also thinking about Worg again: I don't know what Corwin and Krupal
> think, but maybe Worg deserves more maintainers?
>

More maintainers sounds great!

Re: [DISCUSSION] Contributing policy for WORG

[jman]

Joseph Turner <joseph@ushin.org> writes:

> Thanks for the suggestion!  I imagine such a command would do this:
(...)

I am not a Worg contributor but such workflow would definitively scare me off.

Just out of curiosity: what is wrong with a git workflow to contribute to Worg?

Cheers,

Re: [DISCUSSION] Contributing policy for WORG

[Joseph Turner]

jman <emacs-orgmode@city17.xyz> writes:

> Joseph Turner <joseph@ushin.org> writes:
>
>> Thanks for the suggestion!  I imagine such a command would do this:
> (...)
>
> I am not a Worg contributor but such workflow would definitively scare me off.

Understandable :) If we added some sort of bleeding-edge peer-to-peer
way to contribute to worg, it would certainly be in addition to
tried-and-true methods like emailed patches.

> Just out of curiosity: what is wrong with a git workflow to contribute to Worg?

I really like the git+email workflow.  Perhaps we could also benefit
from something like https://git-send-email.io for teaching new Emacs
users how to submit patches with Emacs.  Maybe it could simply teach
people how to use M-x report-emacs-bug or M-x package-vc-prepare-patch.

I think the biggest hurdle is setting up Emacs for email, so maybe we
need a wizard command for that.

Joseph

Re: [DISCUSSION] Contributing policy for WORG

[Bastien Guerry]

Joseph Turner <joseph@ushin.org> writes:

>> I am not a Worg contributor but such workflow would definitively
>> scare me off.
>
> Understandable :) If we added some sort of bleeding-edge peer-to-peer
> way to contribute to worg, it would certainly be in addition to
> tried-and-true methods like emailed patches.

Between the good old patch-based contribution way and the experimental
peer-to-peer way, there is probably yet another (complementary) way.

What about gollum?

https://github.com/gollum/gollum

From what I understand, it would provide a way to let users modify Org
files by editing them from a web interface (without Git knowledge), on
top of rendering the .org files as HTML pages.

Would someone try to set up a proof-of-concept?

-- 
 Bastien Guerry