Guidelines to handling published posts

[TheAssassin]

In some cases, it might be needed to change an already published post. This issue contains some guidelines created from empirical knowledge.

Motivation

It recently happened that the URL to a blog post was changed as it was removed from a blog post. This was done in order to "unpin" it (which didn't work by the way, CC @TobiGr). The problem with this was that by unpinning it, the blog post was no longer available from its old URL which contained the category's name.

Now, there's two problems. First of all, there is no redirection to the new place. Ideally, the blog article's links should not contain any category data. Then, we can change these on demand without breaking any links.

But the IMO bigger issue is that when a URL changes, its comments "vanish". isso associates a list of comments with the public URL. If the URL changes, the page is treated as new. So, whenever a category is changed, the comments are gone.

By eliminating the category data in the URLs, problems like these can be avoided in the future.

But there's additional points to be considered when changing a published blog post.

@TobiGr once we resolve this issue, we need to change the URL associations in the isso database. We need to coordinate the deployment of the fix properly in order to not break the site.

Guidelines

The following list incorporates the most common rules how to deal with already published posts when there is no way other than changing them.

First of all, changes of existing posts shall be avoided by all means. If possible, less invasive method shall be used to provide additional information. If a comment (or a reply to a comment) can achieve the same goals, then a comment shall be used instead.

If editing the post is still necessary, though, then the following, simple rules should be followed.

The original contents shall be preserved, unless some parts need to be removed, e.g., for legal reasons. We store our posts in Git, a versioning system, therefore when a change is necessary, it is likely that the change needs to be applied in the Git history as well. In these cases, a so-called "force push" is explicitly allowed. Please get in touch with the maintainers (@theScrabi, @TobiGr or me) before doing so, we can inform the relevant persons then that their cloned repositories are most likely broken, and how they can fix the issue.

If a section needs to be corrected, the wrong information shall be struck out using Markdown's special syntax ~~incorrect part~~. If new information is to be added, it shall be prefixed with the word Update: ..., and maybe the date of the change (Update (date): ...).

Changes of the article's categories are not permitted until the bug described in the Motivation section is resolved.

Changes of the article's title are not permitted, as the URL is generated from it. If a change is necessary, please use Jekyll's slug parameter in the post's header and copy the value of the generated link into it. If you are not sure about the title, and plan to change it in the future, please use the slug setting right away from the beginning, and choose a simple but unproblematic slug.

For the same reasons category changes are not allowed, please contact the maintainers if a change of the URL is required as well. We will try to set up a redirection, and fix the association in the comments database.

@theScrabi @TobiGr if you have additional rules, please write them down, I will then edit my comment accordingly.

[TobiGr]

once we resolve this issue, we need to change the URL associations in the isso database. We need to coordinate the deployment of the fix properly in order to not break the site.

I'll take a look into this. There should be a solution. Which version of isso is runnig on your server? Were you able to use our custom version from TeamNewPipe/isso? If yes, we should rebase it since there are some interesting changes.

By eliminating the category data in the URLs, problems like these can be avoided in the future.

Since we set the permalinks in config.yml, we can only change the URLs of all posts at once. (It is possible to set permalinks for each post in the post file, but I'd like to avoid this). When you attempt to remove the categories, we need to redirect every post by using the jekyll-redirect-from plugin. This causes some work on isso side. Nevertheless we the could do this and once a solution for the isso problem is found.

The original contents shall be preserved, unless some parts need to be removed, e.g., for legal reasons. We store our posts in Git, a versioning system, therefore when a change is necessary, it is likely that the change needs to be applied in the Git history as well. In these cases, a so-called "force push" is explicitly allowed.

@TheAssassin I don't get why we need override the history.

[TheAssassin]

@TobiGr found a solution, see https://jekyllrb.com/docs/permalinks/. We could change the default URL template /:categories/:year/:month/:day/:title:output_ext to /:year/:month/:day/:title:output_ext for instance.

This causes some work on isso side. Nevertheless we the could do this and once a solution for the isso problem is found.

I already mentioned that once we have proper permalinks, I will edit the URLs by hand in the isso database. See also the rest of the guidelines.

@TheAssassin I don't get why we need override the history.

If we violate any law, we need to change any published form, which obviously includes the Git history that is publicly available. If we want to keep the Git history, we must move at least the posts to a private Git repository with some access control.

Were you able to use our custom version from TeamNewPipe/isso? If yes, we should rebase it since there are some interesting changes.

No, not yet. It still refuses to run in a Docker setup. Feel free to rebase our repository (or simply merge the upstream changes) at any time. I'll post a follow-up once the issues have been resolved.