From 5178fd2d21083389fa277e9728cd0ff6de9f841e Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 23 Sep 2022 08:54:47 -0400 Subject: [PATCH] Move contributing guide to a man page. --- docs/contributing.7 | 244 +++++++++++++++++++++++++++++++++++++++++- site/index.html | 251 +------------------------------------------- 2 files changed, 247 insertions(+), 248 deletions(-) diff --git a/docs/contributing.7 b/docs/contributing.7 index 4718911..1291214 100644 --- a/docs/contributing.7 +++ b/docs/contributing.7 @@ -7,4 +7,246 @@ .Sh DESCRIPTION Telodendria is an open source project. As such, it welcomes contributions. There are many ways you can contribute, and any -way you can is greatly appreciated. +way you can is greatly appreciated. This page contains some of +the ways you can help out. +.Sh REPORTING ISSUES +Please reach out to the Matrix rooms mentioned at the top of +.Xr telodendria 7 . +All issue tracking takes place in those rooms. Start by reaching +out to the general room, and if you think there's a legitimate +problem with Telodendria itself, then stick the issue in the +issues room, where it can be discussed further. Issues usually +remain in the Matrix rooms, but severe enough issues may be put +in a +.Pa TODO +file in the +.Xr cvs 1 +repository so that they don't get lost. +.Sh DEVELOPING +The primary language used to write Telodendria code is ANSI C. +Other languages you'll find in the Telodendria repository include +shell scripts, +.Xr mdoc 7 , +and a little bit of HTML and CSS. If you have any experience with +any of these languages, your contributions are valuable! Please follow +the guidelines on this page to ensure the contribution workflow goes +as smoothly as possible. +.Ss Getting the Code +If you'd like to hack on Telodendria, you'll need the following tools +in addition to a C compiler and POSIX shell: +.Bl -tag +.It Xr cvs 1 +For checking out and updating your local copy of the source code. +.It Xr indent 1 +For formatting your code before generating patches. +.It Xr patch 1 +For applying patches to your local copy of the source code. +.El +.sp +All of these tools are built into OpenBSD. While you don't have to +use OpenBSD to develop Telodendria, it may make the process a bit +easier. In fact, these tools where chosen precisely because they +were built into my operating system of choice. +.sp +You can download an official release tarball from the website if +you would really like, but the preferred way to get the source +code for development is to check it out from CVS. This makes generating +patches a lot easier. +.Bd -literal -offset indent +$ cvs -d anoncvs@bancino.net:/cvs checkout -P Telodendria +$ cd Telodendria +.Ed +.sp +If you already checked out the code previously, make sure you update +your local copy before you start developing: +.Bd -literal -offset indent +$ cvs -q update -dP +.Ed +.sp +You should now have the latest source code. Follow the +.Sx CODE STYLE +as you make your changes. If the +.Xr cvs 1 +command fails with a "Connection refused" error message, try setting +the +.Ev CVS_RSH +environment variable to "ssh", like this: +.Bd -literal -offset indent +$ export CVS_RSH=ssh +.Ed +.sp +Then run the checkout command again. Some versions of CVS on some +systems don't use SSH to checkout by default, so if yours doesn't, +you might want to put the above line into your shell init script. +.Ss Submitting Patches +Telodendria aims at remaining as minimal as possible. This doesn't just +mean minimal code, it also means a minimal development process, which is +why Telodendria doesn't use GitHub, GitLab, or even SourceHut. Instead, +the contribution workflow operates on submitting patch files to a public +Matrix room, sort of like the OpenBSD project operates on patch files +sent to a public mailing list. +.sp +If you're not used to manually creating and submitting patches instead of +just opening a "pull request," you should be pleased to hear that submitting +patches is fairly easy to do if you've got the CVS sources checked out. In +fact, I find it easier than having to make a GitHub account, forking a +project's repository, and then making a pull request for it. Once you have +made your changes in your local copy of the code, and you've configured your +environment properly as noted in the manual for +.Xr td 8 , +just run the patch recipe: +.Bd -literal -offset indent +$ td patch +.Ed +.sp +This will automatically generate a patch file for all your changes, and then +open it in your preferred editor. You can also generate a patch file for only +certain files and directories. To do that, set +.Ev PATCHSET , +like this: +.Bd -literal -offset indent +# Only write a patch for README.txt and the files in docs/ +$ PATCHSET="README.txt docs/" td patch +.Ed +.sp +As you'll notice, the top of the patch file should have some email-style +headers that look like this: +.Bd -literal -offset indent +From: Jordan Bancino <@jordan:bancino.net> +Date: Fri Jul 29 03:21:21 PM EDT 2022 +Subject: Document Patch Procedure +.Ed +.sp +As much information should be filled out for you, such as the date. An +attempt to fill out the From header was also made by +.Xr td 8 , +but the information there can be modifed as necessary. Consult the manual +for +.Xr td 8 +for more details. The Subject should very briefly describe what the patch +is about. +.sp +You'll also notice these lines in the patch: +.Bd -literal -offset indent +[ ] I have read the Telodendria Project development certificate of + origin, and certify that I have permission to submit this patch + under the conditions specified in it. +.Ed +.sp +This is a checkbox that tells me whether or not you actually have the +rights to submit your patch, and that once you submit your patch, your +code is bound by the Telodendria project license, which you can and +should view in +.Xr telodendria 7 . +The full text of the developer certificate of origin is as follows: +.Bl -enum +.It +The contribution was created in whole or in part by me, and I have the right +to submit it under the open source licenses of the Telodendria project; or +.It +The contribution is based upon a previous work that, to the best of my knowledge, +is covered under an appropriate open source license and I have the right under +that license to submit that work with modifications, whether created in whole +or in part by me, under the Telodendria project license; or +.It +The contribution whas provided directly to me by some other person who certified +(1), (2), or (3), and I have not modifed it. +.It +I understand and agree that this project and the contribution are made public +and that a record of the contribution\(emincluding all personal information +I submit with it\(emis maintained indefinitely and may be redistributed +consistent with this project or the open source licenses involved. +.El +.sp +If you agree to the above, fill in the square brackets with an 'x', and then after +the headers, but before the checkbox, write a more thorough description of the +patch and why it was created. Then, send the resulting patch file to the public +Matrix room, as noted in +.Xr telodendria 7 , +so it can be discussed and reviewed by the community. +.sp +Try to keep your patches on topic\(emmake one patch file per feature or bug fix +being implemented. It is okay if your patches depend on previous patches, just +indicate that in the patch description. Note that it may take a while for +patches to be committed, and some patches may not be comitted at all. In either +case, all sent patches are queued from the Matrix room into the public patch +directory, so they can be referenced easier in the future. If you want to +reference a submitted patch in a Matrix message, email, or other digital medium, +it might be a good idea to link to it in the public patch directory. +.sp +The public patch directory works as follows: when you send your patch to the +Matrix room, it is downloaded by Telodendria Bot and placed in the +.Pa ingress/ +directory, named as the message ID. Then, it is assigned a patch ID and +copied to the +.Pa p/ +directory as just "%d.patch", where "%d" is obviously the patch ID. This is +a permanent link that will always reference your patch. Then, your patch will +be symlinked into the +.Pa queue/ +directory. I have a script that automatically ingresses patches and queues them +for me, and I use this to review patches. If your patch is accepted, the queue +symlink will be moved to +.Pa accepted/ +and the submitted patch will be committed to the official CVS repository. +If your patch is rejected for some reason, its symlink will be moved to the +.Pa rejected/ +directory. Regardless of the state of your patch, it will always remain +permalinked in the +.Pa p/ +directory, and when it is accepted or rejected, Telodendria Bot will send a +message to the Matrix room. +.sp +You're always welcome to inquire about rejected patches, and request that they +be reviewed again, or you can use them as a starting point for future patches. +.sp +The public patch directory is located at +.Lk https://telodendria.io/patches/ +.Sh CODE STYLE +In general, these are the conventions used by the code base. This guide +may be slightly outdated or subject to change, but it should be a good +start. The source code itself is always the absolute source of truth, so +as long as you make your code look like the code surrounding it, you should +be fine. +.Bl -bullet +.It +All function, enumeration, structure, and header names are CamelCase. This +is preferred to snake_case because it is more compact. +.It +All variable names are lowerCamelCase. This is preferred to snake_case +because it is more compact. +.It +enumerations and structures are always typedef-ed to their same name. The +typedef should occur in the public API header, and the actual declaration +should live in the implementation file. +.It +A feature of the code base lives in a single C source file that has a +matching header. The header file should only export public symbols; +everything else in the C source should be static. +.It +Except where absolutely necessary, global variables are forbidden to +prevent problems with threads and whatnot. Every variable a function +needs should be passed to it either through a structure, or as a +separate argument. +.It +Anywhere curly braces are optional, there still must be curly braces. This +makes it easier to add on to the code later, and just makes things a bit +less ambiguous. +.El +.sp +As far as actually formatting the code goes, such as where to put brackets, +and whether or not to use tabs or spaces, use +.Xr indent 1 +to take care of all of that. The root of the CVS repository has a +.Pa .indent.pro +that should automatically be loaded by +.Xr indent 1 +to set the correct rules. If you don't have a working +.Xr indent 1 , +then just indicate in your patch that I should run my +.Xr indent 1 +on the code after applying it. Although in reality, I'll likely +run my own +.Xr indent 1 +on the code anyway, just to make sure the spacing is consistent, if nothing +else. diff --git a/site/index.html b/site/index.html index b39f59f..5b1c4e6 100644 --- a/site/index.html +++ b/site/index.html @@ -176,9 +176,10 @@ configure it, as well as contribute to the project. The man pages are also available online for convenience:

Project Status

@@ -192,7 +193,7 @@ getting off the ground and building a foundation. But just because there's nothing here yet doesn't mean you should go away! I could always use help, so you are more than welcome to help out if you want things to go quicker. Please see the -Contributing section for details on how you +contributing(7) page for details on how you can get involved.

@@ -369,250 +370,6 @@ you do though, make sure you're running the latest version of Telodendria and you've thoroughly read through all the relevant documentation.

-

Contributing

-

-Telodendria is an open source project. As such, it welcomes -contributions. There are many ways you can contribute, and any way you -can is greatly appreciated. -

-

Reporting Issues

-

-If—after you've reached out to -#telodendria-general:bancino.net—it has been -determined that there is a problem with Telodendria, it should -be reported to #telodendria-issues:bancino.net. There it -can be discussed further. The issues room serves as the official -issue tracker of Telodendria; although severe issues may be copied -into a TODO file in the CVS repository just so they -don't get lost. -

-

Developing

-

-The primary language used to write Telodendria code is ANSI C. -Other languages you'll find in the -Telodendria repository are shell scripts and HTML. If you have -any experience at all with any of these languages, your contributions -are valuable. Please follow the guidelines in this section to ensure -the contribution workflow goes as smoothly as possible. -

-

Getting The Code

-

-If you'd like to hack on Telodendria, you'll need the following -tools in addition to the tools required to -build the source: -

- -

-Note that all of these tools are built into OpenBSD. While you of course -don't have to use OpenBSD to develop Telodendria, it may make -the process a little easier. In fact, these tools were chosen -precisely because they were built into OpenBSD, the operating -system I use. -

-

-You can download an official release tarball if you would really like, -but the preferred way is to check out the source code from CVS. This -makes generating patches a lot easier. -

-
-$ cvs -d anoncvs@bancino.net:/cvs checkout -P Telodendria -$ cd Telodendria -
-

-If you already checkout out the code previously, make sure you update your -local copy before you start developing: -

-
-$ cvs -q update -dP -
-

-You should now have the latest Telodendria source code. Follow -the Code Style as you make your changes. If -the cvs command fails with a Connection refused -error message, then try setting the CVS_RSH environment -variable to ssh, like this: -

-
-$ export CVS_RSH=ssh -
-

-Then run the checkout again. Some versions of CVS don't use SSH to checkout -by default, so if yours doesn't, you might want to put that line in your -.bashrc or other shell init script. -

-

Code Style

-

-In general, these are the conventions used by the code base. This -guide may be slightly outdated or subject to change, however. The -source code itself is the absolute source of truth, so as long as -you make your code look like the code surrounding it, you should -be fine. -

- -

-As far as actually formatting the code goes, such as where to put -brackets and whether you use tabs or spaces, use indent(1) -to take care of all of that. The root of the repository has a -.indent.pro file that should automatically be loaded by -indent(1) to set the correct rules. If you don't have -access to a working indent(1), just indicate in your patch -that I should run indent(1) on the code after applying it. -I'll likely run my indent(1) on the code anyway though, -just to make sure the spacing is consistent, if nothing else. -

-

Submitting Patches

-

-Telodendria aims at remaining as minimal as possible. This doesn't -just mean minimal code, it also means a minimal development process, which -is why Telodendria doesn't use GitHub, GitLab, or even SourceHut. -Instead, the contribution workflow operates on submitting patch files to -a public Matrix room, sort of like the OpenBSD project operates on patch -files sent to a public mailing list. -

-

-If you're not used to manually creating and submitting patches instead of -opening a "pull request," you should be pleased to hear that submitting -patches is fairly easy to do if you've got the CVS sources checked out. -In fact, I find it easier than having to make a GitHub account, forking -a project repository, and then making a pull request for it. Once you -have made your changes in your local copy of the code, and you've -configured your environment using the instructions in -The Build Script, just run the -patch recipe: -

-
-$ td patch -
-

-This will automatically generate a patch file for all your changes, -and then open it in your preferred editor. -You can also generate a patch for only certain files and directories. -To do that, set PATCHSET, like this: -

-
-# Only write a patch for README.txt and the files in site/ -$ PATCHSET="README.txt site/" td patch -
-

-As you'll notice, the top of the patch file should have some email-style -headers that look like this: -

-
-From: Jordan Bancino <@jordan:bancino.net> -Date: Fri Jul 29 03:21:21 PM EDT 2022 -Subject: Document Patch Procedure -
-

-As much information as possible should be filled out for you, such as -the date. An attempt to fill out the From header was also -made, but the information there can be made more accurate by setting -MXID to your Matrix ID, and DISPLAY_NAME to -your real name in your environment, or the .env file. -The Subject should very briefly describe what the patch -is about. -

-

-You'll also notice these lines: -

-
-[ ] I have read the Telodendria Project developer certificiate of - origin, and certify that I have permission to submit this patch - under the conditions specified in it. -
-

-This is a checkbox that tells me whether or not you actually have -the rights to submit your patch, and that once you submit the patch, -your code is bound by the Telodendria license. The full text of the -developer certificate of origin is as follows: -

-
    -
  1. The contribution was created in whole or in part by me, and I have -the right to submit it under the open source license of the Telodendria -project; or
    2. -
  2. The contribution is based upon a previous work that, to the best -of my knowledge, is covered under an appropriate open-source license -and I have the right under that license to submit that work with -modifications, whether created in whole or in part by me, under the -Telodendria project license; or
    3. -
  3. The contribution was provided directly to me by some other person -who certified (1), (2), or (3), and I have not modified it.
    4. -
  4. I understand and agree that this project and the contribution are -public and that a record of the contribution—including all -personal information I submit with it—is maintained indefinitely -and may be redistributed consistent with this project or the open-source -licenses involved.
    5. -
-

-After the headers, but before the checkbox, write a more thorough -description of the patch and why it was created. Then, send the -resulting patch file to #telodendria-patches:bancino.net, -so it can be discussed and reviewed by the community. -

-

-Try to keep your patches on topic—make one patch file per feature -or bug fix being implemented. It is okay if your patches depend on previous -patches, just indicate that in the patch. Note that it may take a while -for patches to be committed, and some patches may not be committed at -all. In either case, all sent patches are queued from the Matrix room into the -public patch directory, so they can be referenced easier -in the future. If you want to reference a submitted patch in a Matrix message -or email, it might be a good idea to link to it in the public patch directory. -

-

-The public patch directory works as follows: when you send your patch to the -Matrix room, it is downloaded by the Telodendria Bot and placed in the -ingress/ directory, named as the message ID. Then, it is -assigned a Telodendria patch ID and copied to the p/ -directory as just ${id}.patch. This is a permanent link that will -always reference your patch. Then, your patch is symlinked to the -queue/ directory. I have a script that automatically ingresses -patches and queues them for me, and I'll use this to review patches. -If your patch is accepted, the queue symlink will be moved to the -accepted/ directory and the patch is committed to the official -CVS repository. If you patch is rejected for some reason, its symlink will -be moved to the rejected/ directory. Regardless of the state -of your patch, it will always remain permalinked in the p/ -directory, and when it is accepted or rejected, Telodendria Bot will -send a message. -

-

-You're always welcome to inquire about rejected patches, and request they be -reviewed again, or you can use them as a starting point for future patches. -

Resources