olang | O Programming Language

6.3.1 Formatting Patches ¶

All contributors are required to "sign-off" their commits (using git commit -s) to indicate that they have agreed to the Developer Certificate of Origin.

Before submit the patch, ensure the code follows our coding style and is well-tested. (every single patch must pass the test suite)

Unlike many projects, olang has a ’recipe’ style history. The patches should be small, digestible, stand-alone and functional. Rather than a purely chronological commit history.

Bellow there is an example of commit subject:

Subject: [PATCH olang] parser: add bitwise shift binary operator expression
                ^      ^       ^
                |      |       |
                |      |       - patch description
                |      |
                |      - module prefix
                |
                - project name

In the patch body we expect:

1. A good explanation on why this change has been made
2. All lines wrapped at 75 columns, which will be copied to the permanent changelog.
3. An empty line
4. The Signed-off-by: lines
5. A marker line containing simply ---
6. Any additional comments not suitable for the changelog
7. The actual patch (diff output).

Sometimes you might need to break down your patch into multiple patches. In this case a patchset should be sent. Patchesets MUST contain a cover letter followed by a good description. It is easily achievable with the --cover-letter argument available on git format-patch and git send-email commands.

6.3.2 Creating Patches ¶

You can create a patch using the command:

$ git format-patch --cover-letter --base origin/main -M origin/main -o outgoing/

As described on Formatting Patches the option --cover-letter is required for patchset. Check the patches generated on outgoing folder and adjust the cover letter by replacing the "gaps" SUBJECT HERE and BLURB HERE.

We recommend you to add the --base followed by a commit hash to help maintainers to know from where you changes are based on. (Optional but a good practice)

6.3.3 Sending Patches ¶

Before sent patch, we suggest you to set the following properties on your .git/config file (This example assumes you are working on "olang" repository):

[sendemail]
    to = ~johnnyrichard/olang-devel@lists.sr.ht
[format]
    subjectPrefix = PATCH olang

Make sure you email settings is correctly configured by running the https://git-send-email.io tutorial. Once you have everything set, you can send the patches running the git send-email command as described bellow:

$ git send-email outgoing/* --to=~johnnyrichard/olang-devel@lists.sr.ht

6.3.4 The Review Process ¶

IMPORTANT: All emails MUST be written on plain/text format.

Upon submission, you’ll receive an automated email from our pipeline. If the check is successful, the olang maintainers will review your patch. Subsequently, you’ll receive an email indicating whether your patch has been approved, requires changes, or has been rejected.

We use a patch management system to track patch status at https://lists.sr.ht/~johnnyrichard/olang-devel/patches.

Patch status meaning:

‘PROPOSED’

A new patch which needs review.

‘NEEDS_REVISION’

The patch has been reviewed and changes was requested.

‘SUPERSEDED’

The patch has been superseded by a new revision.

‘APPROVED’

The patch has been approve and is waiting to be integrated.

‘REJECTED’

The patch has been rejected and the work MUST be abandoned.

‘APPLIED’

The patch has been integrated into the upstream.

If your patchset requires any modifications, you’ll have to submit a new version of your patch (git is your friend here, use rebase to rewrite the history according to review comments). The submission process remains unchanged, except for the addition of the version argument to the git format-patch command.

$ git format-patch --cover-letter -M origin/main -o outgoing/ -v2

Whenever you need to reply emails comments, please avoid top posting, do bottom posting instead. Read more about it here https://useplaintext.email/#etiquette.