Boilerplate template for POLITICS.md

Inspired by reading http://www.tesio.it/2019/06/03/what-is-informatics.html by @Shamar on our Masto, I’d like to solicit feedback on a basic template for a POLITICS file to include alongside README and LICENSE. I just started writing an npm package for a custom React Hook to use IntersectionObserver so this is of practical relevance to me as well. Here’s what I have so far:

Politics of [project]

Description of this document

The creation and distribution of software do not exist in a vacuum. It is the responsibility of programmers to make statements regarding how they intend for their work to affect the world and not to pretend technology exists or has ever existed separate from the natural tendency for human agents to consolidate power. As such, this document outlines specific and quantifiable political goals for this project and not merely vague principles that corporate entities routinely ignore. 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.

1 Like

Sounds like a fine intro… few things

  1. this is just an intro paragraph, it seems incomplete on its own since you didnt actually list what your political intentions are

  2. I personally think this is better served in a readme or on the website. I dont think it need be present in an open-source code repo itself as a seperate file. But this point isnt particularly important either way, no harm done doing it this way and i see how it might highlight the importance more so.

  3. I’m not sure if “politics” is the right word for a document that basically seems to mean “author’s goals/intentions”. Politics has negative connotations and is more about how a group presents itself (systematically negotiating for mutual interests) than the end goals… Politics is any act that brings about policy (thus the similarity in words). There is probably a better word to capture what you are doing here.

  1. Definitely just an intro for now, I’ll update as I add more to the specific file I’m writing, but I’m hoping to define a generic template for use in all of my projects

  2. Including it in the repo is important to me for the same reason I include a CoC file for contributors. Programmers read repos first then websites and personally, I consider the repo to be the source of truth.

  3. imo, the word politics is controversial rather than strictly negative, but definitely charged. Ostensibly, any free software doesn’t belong to the author, but the world, so including desired politics for the software is relevant to a group’s presentation. Moreover, politics are the means by which humans organize power; strongly encouraging people to, in a phrase, get over their distaste for the word is definitely my prerogative

1 Like

I cut out some of the rhetoric. Given the advice of @Shamar, instead of trying for a generic template, now I’m aiming for a well written specific example. Here’s what I got.

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.

1 Like

I like this one much better, on the right track!

1 Like

ok, I think this is close to if not the final version.

Politics

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, though will not trigger a version bump in 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: 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.

My concern at this point is the bit about not triggering a version bump. A bump in major, minor, or patch seems obviously inappropriate; could a change in this document reflect a change in “build metadata” though? For instance, if the current version is 1.0.5, and POLITICS.md changes, would it be appropriate to release 1.0.5+politics-2.0.0?

1 Like

Version bumping boils down to when you want to do a release, nothing more. SemVer does not dictate WHEN you need to bump the version only HOW you bump it when you do.

If you make a change to the politics file and that is all you do then you likely wont make a release of any kind, nor does SeVer encourage you to do so (even if the change is major).

Similarly another fundemental rule of semantic versioning is that you NEVER do a release of any way shape or form without bumping the version, though this can be sub-patch level). #3 of SemVer covers this explicitly with the wording"

Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.

So your concern is valid, claiming it “should not trigger a version bump” is explicitly against the SemVer rules, in fact it MUST trigger a version bump due to being a new release. What you absolutely cant do is change a released package to have some updated politics file but not change the version (simply replacing the package and keeping the version). That is simply not allowed.

In short I wouldnt mention version bumping at all, as the rules are already covered in SemVer. Specifically if you want to do a new release that only contains changes to the politics file then the correct way to pump the version according to SemVer is, as you suggest, bumping the build metadata version following the plus sign. However as I said this is likely never going to happen as it is unlikely you would go through the trouble of a whole new release just to update a politics file.

1 Like