Reorganize the "How to contribute code" documentation
Open, NormalPublic
Actions

Assigned To

None

Authored By

	dereckson
	Sun, Aug 23, 05:01

Description

I've worked in July in a new simplified Git workflow to use GitHub like we use Gerrit or Phabricator (see below for more context).

That makes me think about two things:

We need to express our model a simple way: we work with CHANGES and not BRANCHES. A change is a mutable work-in-progress commit we amend until it's ready to be added to the main branch.
The How to contribute code document has become operator/maintainer notes more than newcomer onboarding guide

The criticism of the particular harshness of onboarding isn't a new discovery, it has been made vocal several times by @ieli for several years.

Yet, our workflow isn't fundamentally more complicated than GitHub (and I can reproduce it easily at work with GitHub):

Branch → commit → arc diff → review → amend → arc diff → land

I want to reorganize Nasqueron's documentation for contributing code:

The How to contribute code should be more approachable for a newcomer while preserving the existing technical knowledge and our actual workflow
The "tour of the Nasqueron's entire infrastructure before making their first contribution" can be exiled on another page.
No information should be deleted, there are important, but as they are for different audiences (newcomers / developers who contribute / developers who maintain / ops), we can split the page into several ones with pages like "Advanced", "Troubleshooting", or "Project-specific workflow".

The desired outcome is that a newcomer can follow the happy path without reading the entire Nasqueron documentation universe, while an experienced contributor can still find the detailed operational knowledge when needed.

Primary page:
https://agora.nasqueron.org/How_to_contribute_code

Context: I've asked GPT-5.6-Sol to review my personal git-* commands and to prepare a documentation page on https://agora.nasqueron.org/User:Dereckson/Devserver/Git

That documents my commands, mainly to be efficient syncing operations branches between let's say my workstation and Complector, it's not intended to be a general-purpose tool but it would be the foundation of a tool I'd like to write to replace arc.

At the same time, I recognize the number of commands to reimplement an arc (Phabricator) or git-review (Gerrit) workflow in pure sh is a complex machinery and here at Nasqueron there are exceptions and peculiarities than make them even more complex.

That triggers the idea / opportunity to revisit the How to contribute guide to split our two intents: onboarding guide vs troubleshoot the machinery

Event Timeline

dereckson triaged this task as Normal priority.Sun, Aug 23, 05:01

dereckson created this task.

GPT-5.6-Sol proposal: https://chatgpt.com/share/6a8a838d-4cbc-83eb-b59e-5d847a64b03e

The workflow itself has never really been the problem. It's fine, and it maps closely enough to a GitHub PR loop. What's heavy I would say is how much arrives at once on the first contributions, it's equal to too much current for a wire.

What I've seen so far falls into two cases:

they still struggle with Git itself
they know Git but only as clone/commit/push

arc is awkward to explain in both cases. For the first one it stacks a second layer of concepts on an unstable base. For the second it looks like a redundant-ish tool for something they already know how to do, until they hit --amend.

So +1 on the split. Two things that would help most: say CHANGES-not-BRANCHES explicitly and early (a change is one commit you amend), and add a small arc ↔ GitHub mapping, arc diff = open/update the PR, arc land = merge. The infra tour can definitely be exiled for a plug-and-play path.

👍🏻👍🏻👍🏻👍🏻

I confirm the workflow works well.

I sync commits at work (we temporarily use GitHub) with that system:

My laptop:
$ git commit # initial commit
$ git commit --amend && git push origin <branch name> -f # amend and share

Deployment server:
$ git fetch --all && git reset --hard origin/<branch name> # get changes, apply them

I've tested if that works well at Nasqueron too, using datacube/ as exchange point between my laptop, Windriver and Complector.
It does (I only used arc diff to share my last operations diffs, or one time arc amend to get reviewer info / web edit).

That's the personal worfklow I documented on https://agora.nasqueron.org/User:Dereckson/Devserver/Git

We could clearly do something, actually similar to what git-review does to simplify Gerrit use, to offer a better UX (and without having to install PHP)

git phorge <verb to describe the action to send to review>
git phorge amend # amend locally, update automatically the differential too
git phorge land

For deployment workflows:

we can have an optional configuration asking git phorge amend to also automatically push the branch to staging too
we automatically clean branches from the staging server (@DorianWinty requested that several times for datacube AND for Complector)

That would reduce the complexity, the only other Git operations would be the rebase and to solve conflicts, but that's usual Git.

That's the workflow I could test in September at work with a small team of 5 people, of different seniority levels, to see if that's viable.

Reorganize the "How to contribute code" documentationOpen, NormalPublicActions

Description

Event Timeline

Reorganize the "How to contribute code" documentation
Open, NormalPublic
Actions