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.org | 117 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) (limited to 'carbslinux.org') diff --git a/carbslinux.org b/carbslinux.org index dce939b..230b236 100644 --- a/carbslinux.org +++ b/carbslinux.org @@ -74,6 +74,10 @@ with your favorite pager. You can install either the @command{info} or - [[#conventions][Conventions]] - [[#shell-conventions][Shell Conventions]] - [[#repository-conventions][Repository Conventions]] + - [[#contributing-to-the-community-repository][Contributing to the Community repository]] + - [[#sending-patches][Sending Patches]] + - [[#git-patches][Git Patches]] + - [[#fossil-patches][Fossil Patches]] - [[#gnu-free-documentation-license][GNU Free Documentation License]] * Copying @@ -929,6 +933,119 @@ taken literally, they are meant as examples. python setup.py install --prefix=/usr --root="$1" #+END_SRC +** Contributing to the Community repository +:PROPERTIES: +:DESCRIPTION: Package maintainership and issue reports +:END: + +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. + +- {{{contid(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: + + #+begin_example +description: some IRC client with some interesting feature +license: MIT +maintainer: Your Name + #+end_example + + The order of these are not important. However, make sure to use the license + identifiers as defined by [[https://spdx.org/licenses/][SPDX]] when listing the license. + +- {{{contid(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. + +- {{{contid(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. + +- {{{contid(3030)}}} :: + + Package submissions and updates should be submitted in the form of patches to + the [[https://lists.sr.ht/~carbslinux/carbslinux-devel][~carbslinux/carbslinux-devel]] mailing list. The repository on Github is a + read-only mirror, and Pull Requests will *NOT* be accepted. + +- {{{contid(3031)}}} :: + + Issues regarding community packages should be submitted to the + [[https://lists.sr.ht/~carbslinux/carbslinux-discuss][~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 ~. + +** Sending Patches +:PROPERTIES: +:DESCRIPTION: Code contribution +:END: +*** 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=. + +**** =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: + +#+begin_example +[sendemail] + smtpserver = /usr/bin/msmtp + smtpserveroption = -a + smtpserveroption = your-account-name +#+end_example + +**** =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. + +*** 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: + +#+begin_src sh +fossil diff -i > your-changes.patch +#+end_src + +You can also create a binary patch: + +#+begin_src sh +fossil patch create your-changes.db +#+end_src + +If your patchset is complex, and needs to be splitted in multiple check-ins, you +can create a Fossil bundle: + +#+begin_src sh +fossil bundle create --from CHECKIN --to CHECKIN2 patchset.bundle +#+end_src + +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. + * GNU Free Documentation License :PROPERTIES: :APPENDIX: t -- cgit v1.2.3