Update blog post front matter

nzakas commented 2 years ago

For the new website, we'll have categories, tags, authors, and images. In preparation for that, we need to update our existing blog posts (in the _posts directory). This is a great way for new contributors to get started. :)

Each post needs to be updated in the following ways:

1. Make sure every post has a layout specified

All posts should have layout: post in their frontmatter, like this:

layout: post
title: ESLint v8.1.0 released

2. Make sure blog post authors are listed as arrays

Right now we have a mix of properties (using author) and arrays (using authors). We need to standardize to authors even when there's only one author, like this:

layout: post
title: ESLint v8.1.0 released
authors:
- btmills

The first author should be the person who wrote the post and any other authors can come after that (for people who contributed). The new website will only display the first author in a list of blog posts while all authors will be displayed on the individual posts.

3. Make sure every blog post has a category

The categories are:

Announcements - catchall for anything that doesn't fit in other categories
API Changes - announcements about changes in the API or upcoming changes in major releases
Case Studies - we don't actually have any of these yet
Financials - anything discussing how we are spending our donations
Meeting Minutes - we don't have any of these yet
Policy Updates - announcement about changes to how we are doing things (such as changing our policy on how new rules are evaluated)
Postmortems - describing security incidents (currently just one of these, I believe)
Release Notes - self explanatory
Sponsorships - announcements about new sponsorships or large donations
Storytime - anything that tells a story about ESLint
Tutorials - we don't have any of these yet

Categories are specified in the frontmatter using a categories array and should come after authors, such as:

layout: post
title: ESLint v8.1.0 released
authors:
- btmills
categories:
- Release Notes

Each post should have just one category for now but we want to leave open having multiple categories in the future.

4. Make sure every blog post has a teaser

The teaser is 1-3 sentences that hint at the topic of the post. This is what will be shown in a list of blog posts on the new site. For that reason, we need to make sure each post has an appropriate teaser. In some cases the teaser can just be the first paragraph of a post (especially for older release notes) but otherwise should just be a summary of the post. Here's an example:

layout: post
title: ESLint v8.4.1 released
teaser: "We just pushed ESLint v8.4.1, which is a patch release upgrade of ESLint. This release fixes several bugs found in the previous release."
authors:
- mdjermanovic
categories:
  - Release Notes

5. Make sure every blog post has a tags that make sense

We only haphazardly filled in tags on posts because we never really displayed them anywhere. The tags will be displayed on the new site, and so we want to make sure they make sense. In general, tags should be in title case, where each word is capitalized. A lot of the tags we have right now don't make a lot of sense, so we should review, edit, and add tags where necessary. Example:

layout: post
title: ESLint v8.4.1 released
teaser: "We just pushed ESLint v8.4.1, which is a patch release upgrade of ESLint. This release fixes several bugs found in the previous release."
authors:
- mdjermanovic
categories:
  - Release Notes
tags:
- Releases
- Bug Fixes

6. Make sure release notes posts have images specified

We have a different image for each release type:

release-notes.png - the default, for minor releases. This is used when no image is specified in the frontmatter.
release-notes-major.png - for major releases.
release-notes-patch.png - for patch releases.
release-notes-beta.png - for alpha, beta, and release candidate releases.

The image property should come right after teaser, like this:

layout: post
title: ESLint v8.4.1 released
teaser: "We just pushed ESLint v8.4.1, which is a patch release upgrade of ESLint. This release fixes several bugs found in the previous release."
image: release-notes-patch.png
authors:
- mdjermanovic
categories:
  - Release Notes
tags:
- Releases
- Bug Fixes

iamrahulrnair commented 2 years ago

Hey, can i work on this?

nzakas commented 2 years ago

@iamrahulrnair absolutely! And don’t feel like you need to do them all, either. You can start with just one year’s posts and send a pull request for that. If you then want to go on and do more, we would of course appreciate it.

iamrahulrnair commented 2 years ago

Hey, for categories how should i select them? on what criteria i mean?

nzakas commented 2 years ago

Just do your best based on the descriptions of the categories I posted on this issue. It’s not a big deal if you guess wrong, they are easy to fix.

snitin315 commented 2 years ago

@nzakas categories can be multiple, right? For example -

layout: post
title: ESLint v7.0.0 released
tags:
  - release
  - major
authors:
  - kaicataldo
categories:
  - Release Notes
  - API Changes

snitin315 commented 2 years ago

I created a PR that will complete the 3rd and 6th points - https://github.com/eslint/website/pull/897

nzakas commented 2 years ago

There can be multiple categories, yes, but the first will be the primary category.

stephenwade commented 2 years ago

FYI, here is a list of posts that don't have author or authors:

2019-03-04-eslint-v5.15.1-released.md 2019-03-15-eslint-v5.15.2-released.md 2019-03-18-eslint-v5.15.3-released.md 2019-06-24-eslint-v6.0.1-released.md 2019-07-20-eslint-v6.1.0-released.md 2019-08-23-eslint-v6.2.2-released.md 2019-09-30-eslint-v6.5.1-released.md 2019-11-24-eslint-v6.7.1-released.md 2019-11-30-eslint-v6.7.2-released.md 2020-05-22-eslint-v7.1.0-released.md 2020-09-01-eslint-v7.8.1-released.md 2020-09-12-eslint-v7.9.0-released.md 2020-10-09-eslint-v7.11.0-released.md 2020-10-23-eslint-v7.12.0-released.md 2020-10-26-eslint-v7.12.1-released.md 2020-12-18-eslint-v7.16.0-released.md 2021-02-27-eslint-v7.21.0-released.md 2021-03-12-eslint-v7.22.0-released.md 2021-03-26-eslint-v7.23.0-released.md 2021-04-09-eslint-v7.24.0-released.md 2021-04-23-eslint-v7.25.0-released.md 2021-05-07-eslint-v7.26.0-released.md 2021-07-17-eslint-v7.31.0-released.md

snitin315 commented 2 years ago

Thanks, I can update those post with authors in near future.

snitin315 commented 2 years ago

FYI, here is a list of posts that don't have author or authors:

All these posts seem to have authors now, added in https://github.com/eslint/website/pull/897.

snitin315 commented 2 years ago

Working on teaser property - Part 4

nzakas commented 2 years ago

It looks like we've addressed everything so closing. Thanks everyone!

eslint / archive-website