incorporeal-cms/CONTRIBUTING.md

How to Contribute

incorporeal-cms is a personal project seeking to implement a simpler, cleaner form of what would commonly be called a "CMS". I appreciate any help in making it better.

incorporeal-cms is made available under the GNU Affero General Public License version 3, or any later version.

Opening Issues

Issues should be posted to my Gitea instance at https://git.incorporeal.org/bss/incorporeal-cms/issues. I'm not too picky about format, but I recommend starting the title with "Improvement:", "Bug:", or similar, so I can do a high level of prioritization.

Contributions

Sign Offs/Custody of Contributions

I do not request the copyright of contributions be assigned to me or to the project, and I require no provision that I be allowed to relicense your contributions. My personal oath is to maintain inbound=outbound in my open source projects, and the expectation is authors are responsible for their contributions.

I am following the the Developer Certificate of Origin (DCO), also available at DCO.txt. The DCO is a way for contributors to certify that they wrote or otherwise have the right to license their code contributions to the project. Contributors must sign-off that they adhere to these requirements by adding a Signed-off-by line to their commit message, and/or, for frequent contributors, by signing off on their entry in MAINTAINERS.md.

This process is followed by a number of open source projects, most notably the Linux kernel. Here's the gist of it:

[Your normal Git commit message here.]

Signed-off-by: Random J Developer <random@developer.example.org>

git help commit has more info on adding this:

-s, --signoff
    Add Signed-off-by line by the committer at the end of the commit log
    message. The meaning of a signoff depends on the project, but it typically
    certifies that committer has the rights to submit this work under the same
    license and agrees to a Developer Certificate of Origin (see
    http://developercertificate.org/ for more information).

Submitting Contributions

I don't expect contributors to sign up for my personal Gitea in order to send contributions, but it of course makes it easier. If you wish to go this route, please sign up at https://git.incorporeal.org/bss/incorporeal-cms and fork the project. People planning on contributing often are also welcome to request access to the project directly.

Otherwise, contact me via any means you know to reach me at, or bss@incorporeal.org, to discuss your change and to tell me how to pull your changes.

Guidelines for Patches, etc.

• Cloning
  • Clone the project. I would advise using a pull-based workflow where I have access to the hosted repository --- using my Gitea, cloning to a public GitHub, etc. --- rather than doing this over email, but that works too if we must.
  • Make your contributions in a new branch, generally off of master.
  • Send me a pull request when you're ready, and we'll go through a code review.
• Code:
  • Keep in mind that I strive for simplicity in the software. It serves files and renders Markdown, that's pretty much it. Features around that function are good; otherwise, I need convincing.
  • Follow the style precedent set in the code. Do not use Black, or otherwise reformat existing code. I like it the way it is and don't need a militant tool making bad decisions about what is readable.
  • tox should run cleanly, of course.
  • Almost any change should include unit tests, and also functional tests if they provide a feature to the CMS functionality. For defects, include unit tests that fail on the unfixed codebase, so I know exactly what's happening.
• Commits:
  • Squash tiny commits if you'd like. I prefer commits that make one atomic conceptual change that doesn't affect the rest of the code, assembling multiple of those commits into larger changes.
  • Follow something like Chris Beams's post on formatting a good commit message.
  • Please make sure your Author contact information is stable, in case I need to reach you.
  • Consider cryptographically signing (git commit -S) your commits.