From d477d8d3d5878a7b1bbd41cacbce150e9c9404c4 Mon Sep 17 00:00:00 2001 From: Cem Keylan Date: Thu, 2 Dec 2021 07:15:22 +0100 Subject: docs: update contribution guidelines --- carbslinux.txt | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) (limited to 'carbslinux.txt') diff --git a/carbslinux.txt b/carbslinux.txt index 4ea8415..f51b3a1 100644 --- a/carbslinux.txt +++ b/carbslinux.txt @@ -45,6 +45,10 @@ _________________ .. 1. Conventions ..... 1. Shell Conventions ..... 2. Repository Conventions +.. 2. Contributing to the Community repository +.. 3. Sending Patches +..... 1. Git Patches +..... 2. Fossil Patches 5. GNU Free Documentation License @@ -969,6 +973,136 @@ with the info reader. It is divided into sections and easier to read. `---- +4.2 Contributing to the Community repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + The community repository is available for any user to submit + packages. However, there are certain guidelines that the users are + expected to follow before they submit packages. + + [3000] + Any submitted package should contain a `meta' file that includes + a short description of the package, the maintainer's name and + email address, and the license of the package. Below is an + example: + + ,---- + | description: some IRC client with some interesting feature + | license: MIT + | maintainer: Your Name + `---- + + The order of these are not important. However, make sure to use + the license identifiers as defined by [SPDX] when listing the + license. + + [3010] + The user submitting the package is expected to maintain their + packages. This means that they are keeping the packages + up-to-date, and responding to issues related to the package. + + [3020] + If a maintainer doesn't follow the above expectation for a + duration of up to a month, their packages will be orphaned and + can be adopted by a new maintainer. Maintainers can also + request that their packages be orphaned. If the orphaned + packages aren't adopted by a new maintainer in a period of two + weeks, these packages will be dropped from the repository. + + [3030] + Package submissions and updates should be submitted in the form + of patches to the [~carbslinux/carbslinux-devel] mailing + list. The repository on Github is a read-only mirror, and Pull + Requests will *NOT* be accepted. + + [3031] + Issues regarding community packages should be submitted to the + [~carbslinux/carbslinux-discuss] mailing list. When submitting + issues, do not forget to add the maintainer as a recipient. You + can easily find the maintainer information by running + `cpt-maintainer '. + + +[SPDX] + +[~carbslinux/carbslinux-devel] + + +[~carbslinux/carbslinux-discuss] + + + +4.3 Sending Patches +~~~~~~~~~~~~~~~~~~~ + +4.3.1 Git Patches +----------------- + + There are multiple ways of sending patches with git. Unfortunately, + the most popular / official way of doing it requires Perl and some + extra Perl libraries that are not packaged in the repository. This + section tries to list other options that are just as useful as `git + send-email'. + + +* 4.3.1.1 `git-send-email' with msmtp + + By default, `git-send-email' uses a Perl SMTP client, but without + using it this command doesn't actually need extra Perl libraries, only + Perl itself. So, if you are okay with using Perl, the easiest option + is to install the `msmtp' package, and change your git configuration + to match your msmtp settings. + + To your `~/.gitconfig', add the following section: + + ,---- + | [sendemail] + | smtpserver = /usr/bin/msmtp + | smtpserveroption = -a + | smtpserveroption = your-account-name + `---- + + +* 4.3.1.2 `git-imap-send' + + The `git imap-send' command reads patches in mbox format, and uploads + it to your imap server as drafts. You can then use your preferred + email-client to edit and send them. This is the option with no + dependencies. Check out the manual page `git-imap-send(1)' for more + information on setting up. + + +4.3.2 Fossil Patches +-------------------- + + You can create multiple types of "patches" with Fossil. Unlike the + common convention in Git, the first two examples here uses uncommitted + changes to create a patch (although you could very well create patches + of committed changes). The preferred method is by creating a plaintext + patch by doing the following: + + ,---- + | fossil diff -i > your-changes.patch + `---- + + You can also create a binary patch: + + ,---- + | fossil patch create your-changes.db + `---- + + If your patchset is complex, and needs to be splitted in multiple + check-ins, you can create a Fossil bundle: + + ,---- + | fossil bundle create --from CHECKIN --to CHECKIN2 patchset.bundle + `---- + + After creating the patches, you can simply send them to the mailing + list, or upload the patches to the Fossil forum of the relevant + repository. + + 5 GNU Free Documentation License ================================ -- cgit v1.2.3