Soliciting feedback on a boilerplate template for a POLITICS file for free software projects
cc: @Shamar
https://discourse.qoto.org/t/boilerplate-template-for-politics-md/87?u=jump_spider
The POLITICS.TXT should be a short list of easy to verify #political goals of the #software itself.
It's not a general declaration of authors' ethical values or party's affiliation.
It should briefly describe how the software project is intended to chance the society, through clear and verifiable statements.
To be honest I'm not sure you can have a template for this.
For example this is the one of #Jehanne https://github.com/JehanneOS/jehanne/blob/master/POLITICS.md
The word #Politics has been chosen according to its actual meaning: Politics is the art of serving the "#Polis", the society at large (as it was conceived in ancient Greek cities).
Over centuries it has been turned into a game of Power and it's not by chance that today #money drive political movements: money sublimates power and allows its accumulation on large scale.
So today it's important to rediscover Politics as a practical activity with clear and measurable #social goals.
You should write a POLITICS.txt as you would write an architectural description of the application.
There's no prescription in it as there's no way to enforce it on the receivers.
It's just a set of statements that the authors accept to be judged upon, something they will use to measure the political achievements of the project.
Imagine a crypto library: it could be a technical success AND a political failure, and the politics.txt exists to make it easy for everyone to verify this condition.
Since this isn't nearly as established a convention as some other forms of repo boilerplate, you probably want to briefly describe when I must read this document. For example, I should read a Code of Conduct before interacting with others in your project space, the licence before distributing your code, etc.
I got through your introductory paragraph and thought, "Why do your politics matter to me?" As a user I care about how the software helps me reach my goals, not yours.
@khird @Shamar
Good point re: why it should matter to anyone else. I posted this in the Discourse thread, but how does this read?
# Description of this document
The creation and distribution of software do not exist in a vacuum. As such, this document outlines specific and quantifiable political goals for this project. This file is a living document and is expected and encouraged to change over time; changes will be included in the CHANGELOG, though are not suggested to trigger a version bump if using semantic versioning.
## Social goals of react-useintersection
The `IntersectionObserver` api is a powerful JavaScript construct. The author of this package intends for it to help facilitate:
1. **Accessible UX design:** Programmatically determing the intersection of nodes with the screen gives powerful flexibility to control styling and layout.
2. **Wider understanding of advanced JavaScript apis by helping them be more easily used in the React framework:** The `IntersectionObserver` api is but one of several Observer apis in JavaScript, most of which are in the author's opinion relatively unknown to the average programmer because there is a lack of high level packages for them in frameworks such as React.
It's quite a bit clearer now! Cutting out the snarky jabs at people who "pretend technology exists or has ever existed separate from the natural tendency for human agents to consolidate power" and "[mere] vague principles that corporate entities routinely ignore" has helped a lot. You could probably go even further with this, cutting everything before "This document outlines...".
On the other hand, I still don't understand the target audience. It would be nice if fairly early on you say, "This document is required reading for contributors; users can skip it," or whatever is appropriate to your vision for who reads it.
@khird
Well, as @ Shamar clarified, users benefit from reading to understand what the current intent of the project is. For instance, I've been thinking about starting a toy project for Elm, involving generating a yaml for installing and configuring arbitrary tools, but I'm going to limit the scope to asdf and n for language managers. That will be something I include in POLITICS.txt, so users can know upfront that I don't currently intend to support rvm, for example
While you are obviously free to ignore a POLITICS.txt it's pretty obvious it's a rather short sighted decision, at least from a professional perspective.
For example you might build your software upon a library specifically designed to be broken, just to put shame on developers who don't give a shit about politics! 😉
Another example: suppose you want to integrate #Jehanne into a #Web application. I will refuse your pull request, no matter how many people want it and no matter its quality.
The fact is that when you decide to depend on my work, you decide to depend on my goals. Writing down my political goals I let you know what to expect. You are free to ignore it, but at your own risk.
>While you are obviously free to ignore a POLITICS.txt it's pretty obvious it's a rather short sighted decision, at least from a professional perspective.
The problem is that this *isn't* obvious. The various other files you commonly see - LICENCE.txt, CHANGELOG.txt, CONTRIBUTING.txt, etc. - are relevant to specific audiences, and the rest of the world can safely ignore them. It isn't at all obvious until I've read it whether I can ignore POLITICS.txt (in fact, the first time I read it, I was expecting it to contain warnings about exporting cryptography). That's why I think the introduction should detail who's expected to be familiar with its content.
> For example you might build your software upon a library specifically designed to be broken, just to put shame on developers who don't give a shit about politics!
Only insofar as that's true of *any* documentation. You could equally put your warning in a document called RELIGION.txt to spite developers who don't care about that instead.
> The fact is that when you decide to depend on my work, you decide to depend on my goals. Writing down my political goals I let you know what to expect.
Traditionally, developers let people know what to expect by maintaining a roadmap for the project.
Roadmaps are not political goals.
They talk about what is going to happen to the software, not about what we are trying to achieve through the project.
While I have to admit I'd read carefully a RELIGION.txt to understand how a software is related to religious beliefs, I don't think it's the same.
#Software impacts #society in several ways, while it doesn't impact God, usually.
However there are notable exceptions such as #TempleOS that deserve all of our respect.
Anyway, as I said you are free to ignore the political goals of a project at your own risk, just like you can ignore the license or the code they write.
For example I purposedly ignore #CoC because I refuse to adopt an #US workplace like behavior in my #free time.
If forced to read them I look for ways to ridiculize them by violating their letter without violating their rational. So usually it's better for the project leaders to NOT try to impose me their #moralism.
Yet I do this at my own risk.
@Shamar @khird
I think I've reached a final version, per the Discourse thread.
# Description of this document
This document outlines specific political goals and intentions for this project. This file is a living document and is expected and encouraged to change over time; changes will be included in the CHANGELOG.
## Social goals of react-useintersection
The `IntersectionObserver` api is a powerful JavaScript construct. The author of this package intends for it to help facilitate:
1. **Accessible UX design:** Programmatically determining the intersection of nodes with the screen gives powerful flexibility to control styling and layout.
2. **Wider understanding of advanced JavaScript apis:** The `IntersectionObserver` api is but one of several Observer apis in JavaScript, most of which are in the author's opinion relatively unknown to the average programmer because there is a lack of high level packages for them in frameworks such as React.
3. **Demonstrable testing practices for React outside of the Jest ecosystem:** Jest is a powerful testing framework; however, in the author's opinion, it is worthwhile to be familiar with more than one tool, as every tool is "more than a hammer." In specific, Jest is ideally suited for large projects, and is arguably overkill for small components such as `react-useintersection`.
@jump_spider cool ill check it out