[Galene] [RFC] Contributing guidelines[RFC] Contributing guidelines

[Galene] [RFC] Contributing guidelines[RFC] Contributing guidelines

[Valent@MeshPoint]

[-- Attachment #1: Type: text/plain, Size: 3688 bytes --]

Hi,

I could find no written rules for contributors, so new contributors (me 
included) keep making the same mistakes in PRs.  I collected what 
Juliusz wrote about this in reviews on the list and on GitHub since 
2020, and put it into the draft below.
Comments are welcome.

A few things I could not find:

1. Is a short first line enough for a commit message, or do you want a 
body too?

2. Is there a style for Go, CSS and JS beyond the surrounding code?

3. What testing do you expect for UI changes?

4. Should this be a CONTRIBUTING.md file, or a section of the README?

Thanks,

-- Valent

# Contributing to Galene

Galene is distributed under the MIT licence, and all contributions are
published under the same licence.  No CLA is required.

## Where to send

You may either send patches to the mailing list
<galene@lists.galene.org>, or submit a pull request on GitHub.  Please
use one or the other, not both.

General and technical discussion belongs on the mailing list, not on
GitHub.  Bug reports go to GitHub issues.  Ideas are welcome, even if
they are not accompanied with patches.

## What is likely to be accepted

Galene is meant to be easy to install and to have minimal dependencies.
Before writing a large feature, please ask on the list.

   - Respect user privacy.  Contributions that expose private user data,
     such as IP addresses or user names, will not be accepted.
   - Don't harm performance, especially in the server.
   - Avoid heavy libraries, unless they are loaded lazily.  Anything that
     requires an external daemon (e.g. an SQL server) is out of the
     question.
   - Explain what problem the change solves.  Once a feature is included,
     it is difficult to remove, so only features that are actually needed
     are included.

Please don't be discouraged if your first attempt is not accepted.

## Preparing a pull request

   - Use a dedicated branch for each pull request, based on current
     master.
   - Every commit should be a self-contained change.  Unrelated changes 
go
     into a separate pull request.
   - Every commit must compile and must not break any functionality.
   - No merge commits.  Rebase on master instead.
   - Squash your work-in-progress commits before submitting (use
     `git rebase -i`).  When you fix something during review, squash the
     fix into the commit it belongs to.
   - Don't leave commented-out code.
   - Remove "WIP" from the title when the pull request is ready for 
review.

## Commit messages

The first line is a short summary of what the commit does, starting with
a verb and ending with a period:

     Handle overflow in the user list.

If needed, add a blank line and a short paragraph that explains the
problem and the solution.  Don't describe the history of the pull
request.  A verbose commit message is not more useful than a short one.

## Code

   - Follow the style of the surrounding code.
   - Add tests for server code where it makes sense.
   - The JavaScript code is checked with the TypeScript compiler.  Please
     check your changes with `tsc` before submitting.
   - Comments should explain why, not what.  Don't paraphrase the code 
and
     don't repeat the documentation; such comments get out of sync when
     the code changes.
   - Prefer short, simple code.  Code that is verbose or redundant is 
hard
     to review and hard to maintain.
   - In the client, avoid making the logic depend on details of the user
     interface.

## Review

Please answer questions during review.  Pull requests without a reply
from the submitter are eventually closed.

[-- Attachment #2: Type: text/html, Size: 5183 bytes --]

[Galene] Re: [RFC] Contributing guidelines[RFC] Contributing guidelines

[Juliusz Chroboczek]

Just to avoid any misunderstandings: these "rules" have not been discussed
with me, and many of them do not accurately reflect my position.

-- Juliusz

[Galene] Re: [RFC] Contributing guidelines[RFC] Contributing guidelines

[MeshPoint / Valent Turkovic]

[-- Attachment #1: Type: text/plain, Size: 1041 bytes --]

Hi there,

I apologise if my email arrived incorrectly. I’m not suggesting these 
are the rules; I’m simply proposing a framework to start a discussion 
about a contribution guideline. Most projects have guidelines to 
facilitate participation, so it’s easier for new contributors to join 
in. What are the community standards and rules or guidelines that you 
propose?

I found these in mailing list archives, but they could be wrong of 
course.

So you can completely ignore my suggested list, but please propose some 
basic contributor guidelines.

— Valent




------ Original Message ------
From "Juliusz Chroboczek" <jch@irif.fr>
To "Valent@MeshPoint" <valent@meshpointone.com>
Cc "galene@lists.galene.org" <galene@lists.galene.org>
Date 31.10.2026. 16:29:52
Subject Re: [Galene] [RFC] Contributing guidelines[RFC] Contributing 
guidelines

>Just to avoid any misunderstandings: these "rules" have not been discussed
>with me, and many of them do not accurately reflect my position.
>
>-- Juliusz

[-- Attachment #2: Type: text/html, Size: 2856 bytes --]

[Galene] Re: [RFC] Contributing guidelines[RFC] Contributing guidelines

[Juliusz Chroboczek]

> I’m not suggesting these are the rules; I’m simply proposing a framework
> to start a discussion about a contribution guideline.

Valent, you have published an authoritative-sounding document that
contains a number of incorrect statements.  You did not include
a disclaimer.  Since this list is being archived, this document will
appear in web searches, and induce potential contributors in error.

Here's a few examples.  You say

>    Contributions that expose private user data, such as IP addresses or
>    user names, will not be accepted.

That's formulated in a very categorical manner.  Please see commit
a76f225b (the /identify command), which exposes IP addresses.  This
protocol extension was carefully designed to balance the needs of users
(who want their privacy respected) and the needs of moderators (who want
to be able to ban an IP address that's being used for abuse).  (The
original proposal was to log all IP addresses, which I rejected for
privacy reasons.  We then had a bunch of back-and-forth discussion, which
lead to the /identify command.)

>   Anything that requires an external daemon (e.g. an SQL server) is out
>   of the question.

Again, that's formulated in a very categorical manner (was it written by
an LLM?).  It is plainly incorrect.  There are features in Galene that
require an external server (galene-ldap, galene-sip).  A more correct
statement would that it must remain possible to make a simple deployment
of Galene without relying on external servers.  (And even that is not
quite correct: you need working DNS and an X.509 provider.)

>  - Use a dedicated branch for each pull request, based on current master.

That's rather patronising: it implies that we're entitled to tell people
how to organise their work in their private repository.  As long as people
send usable pull requests or patches, we have no right to tell them what
to do in the privacy of their local repository.

I could go on, but I think you get the point.  Valent, please do not
publish further authoritative-sounding lists without including a clear
disclaimer.

-- Juliusz