aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorCem Keylan <cem@ckyln.com>2021-12-02 07:15:22 +0100
committerCem Keylan <cem@ckyln.com>2021-12-02 07:15:22 +0100
commitd477d8d3d5878a7b1bbd41cacbce150e9c9404c4 (patch)
tree84b22fc6d578deffccd135b2ea845ae8c7758948
parent62a4ea580ce9d0480a85526be68b62b203b0fd1d (diff)
downloaddocs-master.tar.gz
docs: update contribution guidelinesHEADmaster
-rw-r--r--carbslinux.org117
-rw-r--r--carbslinux.texi129
-rw-r--r--carbslinux.txt134
-rw-r--r--install.org2
4 files changed, 381 insertions, 1 deletions
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 <address@example.com>
+ #+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 <pkg>~.
+
+** 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
diff --git a/carbslinux.texi b/carbslinux.texi
index fd0973d..6c98bc5 100644
--- a/carbslinux.texi
+++ b/carbslinux.texi
@@ -129,12 +129,19 @@ Display Systems
Contribution Guidelines
* Conventions:: Conventions of the distribution
+* Contributing to the Community repository:: Package maintainership and issue reports
+* Sending Patches:: Code contribution
Conventions
* Shell Conventions:: Conventions for shell scripts
* Repository Conventions:: Conventions for repository build scripts
+Sending Patches
+
+* Git Patches::
+* Fossil Patches::
+
@end detailmenu
@end menu
@@ -867,6 +874,8 @@ and changes may occur with good reasoning.
@menu
* Conventions:: Conventions of the distribution
+* Contributing to the Community repository:: Package maintainership and issue reports
+* Sending Patches:: Code contribution
@end menu
@node Conventions
@@ -1108,6 +1117,126 @@ python setup.py install --prefix=/usr --root="$1"
@end example
@end enumerate
+@node Contributing to the Community repository
+@section 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.
+
+@table @asis
+@item [@anchor{3000}3000]
+Any submitted package should contain a @samp{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:
+
+@example
+description: some IRC client with some interesting feature
+license: MIT
+maintainer: Your Name <address@@example.com>
+@end example
+
+The order of these are not important. However, make sure to use the license
+identifiers as defined by @uref{https://spdx.org/licenses/, SPDX} when listing the license.
+
+@item [@anchor{3010}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.
+
+@item [@anchor{3020}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.
+
+@item [@anchor{3030}3030]
+Package submissions and updates should be submitted in the form of patches to
+the @uref{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 @strong{NOT} be accepted.
+
+@item [@anchor{3031}3031]
+Issues regarding community packages should be submitted to the
+@uref{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 @code{cpt-maintainer <pkg>}.
+@end table
+
+@node Sending Patches
+@section Sending Patches
+
+@menu
+* Git Patches::
+* Fossil Patches::
+@end menu
+
+@node Git Patches
+@subsection 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 @samp{git send-email}.
+
+@enumerate
+@item
+@samp{git-send-email} with msmtp
+
+
+By default, @samp{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 @samp{msmtp} package,
+and change your git configuration to match your msmtp settings.
+
+To your @samp{~/.gitconfig}, add the following section:
+
+@example
+[sendemail]
+ smtpserver = /usr/bin/msmtp
+ smtpserveroption = -a
+ smtpserveroption = your-account-name
+@end example
+
+@item
+@samp{git-imap-send}
+
+
+The @samp{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
+@samp{git-imap-send(1)} for more information on setting up.
+@end enumerate
+
+@node Fossil Patches
+@subsection 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:
+
+@example
+fossil diff -i > your-changes.patch
+@end example
+
+You can also create a binary patch:
+
+@example
+fossil patch create your-changes.db
+@end example
+
+If your patchset is complex, and needs to be splitted in multiple check-ins, you
+can create a Fossil bundle:
+
+@example
+fossil bundle create --from CHECKIN --to CHECKIN2 patchset.bundle
+@end example
+
+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.
+
@node GNU Free Documentation License
@appendix GNU Free Documentation License
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 <address@example.com>
+ `----
+
+ 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 <pkg>'.
+
+
+[SPDX] <https://spdx.org/licenses/>
+
+[~carbslinux/carbslinux-devel]
+<https://lists.sr.ht/~carbslinux/carbslinux-devel>
+
+[~carbslinux/carbslinux-discuss]
+<https://lists.sr.ht/~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
================================
diff --git a/install.org b/install.org
index 21ba261..c0b1f0a 100644
--- a/install.org
+++ b/install.org
@@ -1,4 +1,4 @@
-# Created 2021-10-20 Wed 17:22
+# Created 2021-12-02 Thu 07:15
#+TITLE: Carbs Linux Installation Guide
#+AUTHOR: Cem Keylan
These are the step-by-step instructions for installing Carbs Linux. It can be