From 7a091c5b93c3482130edbc6036e258c12baa04df Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 9 Sep 2023 16:50:38 -0400 Subject: [PATCH] Add contributing documentation. --- .gitea/pull_request_template.md | 25 +++ docs/CONTRIBUTING.md | 161 +++++++++++++++++ docs/user/install.md | 11 +- man/man7/telodendria-contributing.7 | 268 ---------------------------- 4 files changed, 196 insertions(+), 269 deletions(-) create mode 100644 .gitea/pull_request_template.md create mode 100644 docs/CONTRIBUTING.md delete mode 100644 man/man7/telodendria-contributing.7 diff --git a/.gitea/pull_request_template.md b/.gitea/pull_request_template.md new file mode 100644 index 0000000..24cea71 --- /dev/null +++ b/.gitea/pull_request_template.md @@ -0,0 +1,25 @@ + +--- + +Please review the developer certificate of origin: + +1. 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 +1. 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 +1. The contribution was provided directly to me by some other person +who certified (1), (2), or (3), and I have not modified it. +1. I understand and agree that this project and the contribution are +made 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. + +- [ ] I have read the Telodendria Project development certificate of +origin, and I certify that I have permission to submit this patch +under the conditions specified in it. + diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..23ed244 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,161 @@ +# Contributing + +Telodendria is a fully open source project. As such, it welcomes +contributions. There are many ways you can contribute, and any way you +can is greatly appreciated. This document details the ways you can +contribute, and how to go about contributing. + +## Sponsoring Telodendria + +If you would like to sponsor Telodendria, see the +[Sponsorship](../README.md#sponsorship) section on the main project +page. Donations of any size are greatly appreciated. + +## Reporting Issues + +An important way to get involved is to just report issues you find with +Telodendria during experimentation or normal use. To report an issue, +go to [Issues](/Telodendria/telodendria/issues) → +[New Issue](/Telodendria/telodendria/issues/new) and follow the +instructions. + +> **Note:** GitHub issues are not accepted. Issues may only be +> submitted to the official [Gitea](https://git.telodendria.io) +> instance. + +### Feature Requests + +Feature requests are allowed, but note that they are low-priority in +comparison to existing issues and features. That being said, don't +hesitate to submit feature requests. Just select the "Feature Request" +option when submitting an issue. + +## Developing + +If you want to write code for Telodendria, either to fix an issue or +add a new feature, you're in the right place. Please follow all the +guidelines in this document to ensure the contribution workflow goes +as smoothly as possible. + +### Who can develop Telodendria? + +Everyone is welcome to contribute code to Telodendria, provided that +they are willing to license their contributions under the same license +as the project itself. + +The primary language used to write Telodendria code is ANSI C. Other +languages you'll find in the Telodendria repository include shell +scripts, `mdoc`, a little bit of HTML and CSS, and `Makefiles`. +Experience with any of these is preferred, but if you want to use +Telodendria to learn, that's okay too! Telodendria's code base should +hopefully be a good learning tool, and if you are serious about +submitting quality work, we'll guide you through the process and +offer suggestions. + +### What do I need? + +You'll need a couple of things to develop Telodendria: + +- A Unix-like operating system that provides standard POSIX behavior, +or the Windows Subsystem for Linux (WSL), Cygwin, or Msys2 if you are +running Windows. +- A C compiler capable of compiling ANSI C89 code (pretty much all of +them do—pick your favorite, and if you find it doesn't work, +open an issue!). +- `make` for building the project. +- `git` for managing your changes. + +Optionally, you may also find these tools helpful: + +- `indent` for formatting code. +- `valgrind` for debugging particularly nasty issues. + +### Getting The Code + +Telodendria is developed using Git. The easiest way to contribute +changes is to fork the main repository, and then creating a pull +request to ask us to pull your changes into our repo. + +1. If you don't have an account on the +[Gitea instance](https://git.telodendria.io), create one and sign in. +1. Fork this repository. +1. In your development environment, clone your fork: + ```shell + git clone https://git.telodendria.io/[YOUR_USERNAME]/telodendria.git + cd telodendria + ``` + + Please base your changes on the `master` branch. If you need help + getting started with Git, that is beyond the scope of this + document, but you can find many good tutorials on the web. + +### Building & Running + +Telodendria uses the `make` build system. + +**TODO:** Update this section before #19 is closed. Provide quick +make, run, and install directions (maybe just redirect to Porting for +install directions), then list all the `make` recipes. Shouldn't be +as many as were in `td`. + +### Pull Requests + +> **Note:** Telodendria does not accept GitHub pull requests at this +> time. Please submit your pull requests via Gitea. + +Telodendria follows the standard pull request procedures. Once you have +made your changes, committed them, and pushed to your fork, you should +be able to open a pull request on the main repository. When you do, you +will be prompted to write a description + +### 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. + +- All function, enumeration, structure, and header names are +`CamelCase`. This is preferred to `snake_case` because it is more +compact. +- All variable names are `lowerCamelCase`. This is preferred to +`snake_case` because it is more compact. One exception to this rule is +if a variable name, such as a member of a struct, directly represents +a JSON key in an object specified by the Matrix specification, which +may be in `snake_case`. +- 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, unless +the enumeration or structure is intended to be made fully public. +- 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. +- 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. +- Anywhere that C allows curly braces to be optional, there still must +be curly braces. This makes it easier to read the code by making it +less ambiguous, and it makes it easier to add on to the code later. + +As far as actually formatting the code goes, such as where to put +brackets, and whether or not to use tabs or spaces, use `indent` to +take care of that. The repository contains a `.indent.pro` that should +automatically be loaded by `indent` to set the correct rules. If you +don't have a working `indent`, then just indicate in your pull +request that I should run my `indent` on the code. + +### Documentation + +This project places a strong emphasis on documentation. Well-documented +code is fundamental to a successful project, so when you are writing +code, please also make sure that it is documented appropriately. + +- If you are adding a header, make sure you add the necessary comments +detailing the header and the functions in it. +- If you are adding a function, make sure you add the necessary +comments to the appropriate header. + +If your pull request does not also include proper documentation, it +will likely be rejected. diff --git a/docs/user/install.md b/docs/user/install.md index 56a8f30..7d955bd 100644 --- a/docs/user/install.md +++ b/docs/user/install.md @@ -48,4 +48,13 @@ binaries. ## From Source -**TODO:** Update this section before #19 is closed. +If you would like to build Telodendria from source, you can download +the latest release code from the +[Releases](/Telodendria/telodendria/releases) page. After extracting +the tarball, read +[Contributing → Developing → Building & Running](../CONTRIBUTING#building-and-running) +for details on how to build Telodendria. + +If all goes well, you will find the server binary in the `build/` +directory. If an error occured, and you didn't modify the code, +please open an issue. diff --git a/man/man7/telodendria-contributing.7 b/man/man7/telodendria-contributing.7 deleted file mode 100644 index 1aceb96..0000000 --- a/man/man7/telodendria-contributing.7 +++ /dev/null @@ -1,268 +0,0 @@ -.Dd $Mdocdate: March 10 2023 $ -.Dt TELODENDRIA-CONTRIBUTING 7 -.Os Telodendria Project -.Sh NAME -.Nm telodendria-contributing -.Nd Guide to contributing to the Telodendria project. -.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. 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 1 , -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 1 , -but the information there can be modifed as necessary. Consult the manual -for -.Xr td 1 -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 using -.Xr send-patch 1 . -.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. -.Pp -This project places a strong emphasis on documentation. Well-documented -code is fundamental to a successful project, so when you are writing code, -please also make sure it is documented appropriately. -.Bl -bullet -.It -If you are adding a header, make sure you add a man page that documents -all the functions in the header. -.It -If you're adding a function, make sure you add documentation for it -to the appropriate man page for the header that your function resides -in. Do note that you do not have to document static functions, only -public API functions. -.El -.Pp -If your patch does not also include proper documentation, it will -likely be rejected.