[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 --]