Add a style guide to the blog contributing doc - #624
Conversation
|
Warning Review limit reached
Next review available in: 57 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughChangesBlog contribution guide
Suggested reviewers: Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Adds a 'How to write it' subsection to Step 2, matching the format of the existing tips list. The one-sentence-per-line rule is the functional one: GitHub anchors review suggestions to lines, so a paragraph written as a single long line forces every suggestion to restate the whole paragraph. The doc follows its own guidance. Signed-off-by: Madelyn Olson <madelyneolson@gmail.com>
9f48f34 to
b630149
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
CONTRIBUTING-BLOG-POST.md (1)
76-76: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick winPreserve fixed Valkey names in executable examples.
Apply inclusive terminology to prose and identifiers that authors control. Preserve exact Valkey commands, configuration keys, and API names required by the target version. Otherwise, authors may publish snippets that do not execute.
Suggested wording
-8. Use inclusive terminology in prose, diagrams, and code: primary and replica, allowlist and denylist. +8. Use inclusive terminology in prose, diagrams, and code that you control: primary and replica, allowlist and denylist. + Preserve exact Valkey command, configuration, and API names in executable examples. + Explain legacy terms when they are required by the interface.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@CONTRIBUTING-BLOG-POST.md` at line 76, Update the terminology guidance in the numbered contribution rule to distinguish author-controlled prose and identifiers from fixed Valkey syntax: require inclusive terms for prose, diagrams, and renameable code identifiers, while preserving exact Valkey commands, configuration keys, and version-required API names in executable examples.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CONTRIBUTING-BLOG-POST.md`:
- Line 80: Update the image accessibility guidance in CONTRIBUTING-BLOG-POST.md
to require alt text that communicates an informative image’s purpose,
information, or related action rather than merely describing visible content.
Also specify that decorative images must use empty alt text.
- Around line 66-68: Update the Valkey guidance in the contribution instructions
to require recording the exact release or commit, build and configuration
details, hardware, and workload used for each benchmark. Retain “latest” only as
the selection rule at test time, and preserve the requirement to explain
deviations from the default configuration.
---
Nitpick comments:
In `@CONTRIBUTING-BLOG-POST.md`:
- Line 76: Update the terminology guidance in the numbered contribution rule to
distinguish author-controlled prose and identifiers from fixed Valkey syntax:
require inclusive terms for prose, diagrams, and renameable code identifiers,
while preserving exact Valkey commands, configuration keys, and version-required
API names in executable examples.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 13449f0a-d89b-4a3b-a89a-eb4add911575
📒 Files selected for processing (1)
CONTRIBUTING-BLOG-POST.md
jaduffy
left a comment
jaduffy
left a comment
There was a problem hiding this comment.
I think we should have two follow on AIs:
- Create a canonical reference of what a good blog post looks like with all of the Markdown examples for images, frontmatter, etc.
- Consider creating a blog review bot that automatically performs a review against the guidelines on PR submission.
| 2. You can hedge when there is uncertainty, but say where it comes from: “we have not measured this on ARM”, not “this should probably be fine”. | ||
| 3. Make every claim checkable. | ||
| Give numbers with their units and the setup that produced them, link behavior claims to a pull request or the docs, and name the version a behavior applies to. | ||
| 4. Use default or stock Valkey when possible. |
There was a problem hiding this comment.
4. Use the latest version of Valkey with default configurations when possible.
?
| Reviewers use these as the basis for suggestions, so knowing them up front saves a round trip. | ||
| This document follows them, so read its source as an example. | ||
|
|
||
| 1. Put one sentence per line in the markdown source. |
There was a problem hiding this comment.
This makes technical sense but might encourage LinkedIn-like staccato writing.
| 2. Blog posts should cover a topic entirely. | ||
| 1. If you start writing and realize that your post will be super long, consider refining your topic. | ||
| 2. Sometimes there are very good reasons to link multiple posts together, but length is not one; aim to make each post independent and not part of a series. | ||
| 3. Highly technical is fine but understand that [valkey.io](http://valkey.io/) is read by a variety of skill levels: the best posts make complex topics easy to understand. |
There was a problem hiding this comment.
I'd go farther and say a well-written technical blog starts by setting appropriate context for technical people unfamiliar with the topic.
| 1. Acceptable Example: A post that describes the lessons learned about operating Valkey at scale gleaned from a Valkey service provider. | ||
| 2. Unacceptable Example: A post that describes the advantages of running Valkey through a specific service. | ||
| 5. Write about Valkey. | ||
| There is a ton of things to say about Valkey without venturing into comparisons with other products and projects. |
There was a problem hiding this comment.
How do we square this with Redis head to head comparisons for e.g. performance?
There was a problem hiding this comment.
We don't. We always publish head to head comparisons on other platforms. Valkey.io is only for comparing Valkey with previous versions.
| 7. Write descriptive headings, not clever ones. | ||
| Make sure each header is clear to the end user. | ||
| Feel free to make creative jokes and puns, but not at the expense of reading for our global audience. | ||
| 8. Use inclusive terminology in prose, diagrams, and code: primary and replica, allowlist and denylist. |
There was a problem hiding this comment.
The only 4 I typically enforce are primary, replica, allowlist, denylist. Everything else is like, use the code of conduct types of things. I can rewrite that to be explicit.
| 9. Use uppercase backticks for commands like `SET` and `XADD`. | ||
| 10. Use lowercase backticks when describing executable names, configs, and info fields like `valkey-server` and `cluster-node-timeout`. | ||
| 11. Tag code blocks with a language so that they render correctly. | ||
| 12. Give images alt text describing what they show to make them more inclusive. |
|
|
||
| Blog posts on [valkey.io](http://valkey.io/) need to have at least one author. | ||
| This needs to be a person: it does not need to be birth name or even a traditional name, but it can’t be a collective (e.g. “The Good Code Team” would be unacceptable). | ||
| Ideally, this you write under a transparent and accountable name where you can be identified in the Valkey community. |
There was a problem hiding this comment.
Ideally you will publish with a name the Valkey community can connect to your other contributions.
| Ideally, this you write under a transparent and accountable name where you can be identified in the Valkey community. | ||
|
|
||
| Each author needs to have a biography. | ||
| The bio should be 1-2 paragraphs in length and should tell the reader who you are. |
There was a problem hiding this comment.
If you identify as an employee of a company, make sure your employer is okay with you doing so in the blog.
| [Valkey.io](http://valkey.io/) uses Zola to build the website: each page requires what’s called *frontmatter*. | ||
| *Frontmatter* is a short snippet of [TOML](https://toml.io/en/) surrounded by `+++` that defines metadata about your post. | ||
|
|
||
| Here is an example of the frontmatter: |
There was a problem hiding this comment.
We should create a canonical blog post example that follows all guidance and contains examples for frontmatter, image alt tags, etc.
| Write your blog post in markdown. | ||
| Generally, you’ll be better off sticking to headings, links, paragraphs and code blocks (there is no prohibition of using other markdown features though). | ||
|
|
||
| ### What to write about |
There was a problem hiding this comment.
Have we considered a list of outstanding topics we want someone to write about?
There was a problem hiding this comment.
There are some issues. @stockholmux also has a list that he is working through and fanning out.
3 participants
Adds a
How to write itsubsection to Step 2 of the blog contributing guide.It captures the style guidance reviewers already apply, so contributors can see it before the first review round rather than during it.
The one rule with a functional reason behind it is one sentence per line.
Markdown joins the lines back into a paragraph, so nothing changes about how a post renders.
It changes review: GitHub anchors suggestions to lines, so a reviewer can rewrite a single sentence instead of restating the whole paragraph, and two reviewers touching different sentences don't conflict.
The rest covers weasel words, checkable claims, benchmarking on stock Valkey, crediting contributors, active voice, headings, inclusive terminology, and formatting conventions.
The section follows its own guidance, so its source doubles as an example.