docs(community): write a guide for packaging Falcon

[vytas7]

Here's my first stab at creating the packaging guide 😅

Closes #2081.

This guide is not aimed at the packaging mechanics of a specific distribution, but rather general guidelines and ideas from our perspective. For reference, we were considering our own Ubuntu/Debian PPA at some point (see #1061 by @jmvrbanac), but it has never materialized, and unfortunately we don't really have the bandwidth for that kind of project.

We do want to make a packager's life easier as much as we can though (not just giving a 🖕 pointing to our CI as some other Python project maintainers do that we won't name here cough), and I hope 4.0.0 was a step in the right direction.

We sincerely appreciate the work that you put into maintaining Falcon package for various Linux distributions, Conda Forge, etc. 💯

Let me know if you have any feedback; just jot it down here on the PR, or drop a message on Discussions or Gitter.

@carlwgeorge @thomasgoirand @stefanor @tacerus @dvzrv @carlodri @synapticarbors @mweinelt

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (cf51816) to head (5a45485).
Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff            @@
##            master     #2409   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           64        64           
  Lines         7726      7726           
  Branches      1071      1071           
=========================================
  Hits          7726      7726           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[carlwgeorge]

Wow. I'm seriously impressed at how thoughtful and thorough this is. Thank you so much for taking the time to write it! I see no problem merging it in the current state.

Some optional suggestions, either for the current PR or for later:

It would be nice for this guide to include a link to the changelog so packagers know where to look out for breaking changes. Most distributions have update policies about what is and what isn't appropriate for their various release channels. It's not hard to find, but this would be a great place to mention it as well.

On a related note, it helps packagers to know if older major versions (or branches) are still considered maintained, and for how long. Some projects explicitly only consider the absolute latest version maintained. Others maintain the current and previous major version. Unfortunately most projects provide no guidance at all. Some good clear examples I can point to are MariaDB and Redis. A clear lifecycle like this can be a factor when distributions are considering if an update is appropriate in a particular release channel. For instance, in EPEL 9 (add-on repo for CentOS/RHEL 9), I have version 3.1.3. If you still consider version 3 maintained to some extent, I feel more comfortable sticking with that version in that channel long term. If it is intended that there will never be another version 3 release, even for security fixes, then I'll know that I should be prepared to do an incompatible upgrade if a security issue arises.

[vytas7]

Thank you for your kind words and suggestions @carlwgeorge!
I will add a link to the changelog, and assure that we strictly follow SemVer.

Your second point is trickier; I'm afraid we don't have a definite answer. This is very good feedback, and I agree that we ought to have a clear policy on what is considered maintained (both actively, and security updates only), and for how long. We'll discuss this, and try to formulate it. Given our limited resources and (currently) the lack of corporate backing, you might guess which decision this gravitates toward, but we'll see.

Edit: I've captured this in a separate issue: #2410.

[CaselIT]

left some comments. overall it's fine!

[vytas7]

Merged, the rendered version is now available at https://falcon.readthedocs.io/en/latest/community/packaging.html (the unstable, "latest" version of our docs).