Merge pull request #89 from stockholmux/contributing-blog-post

Contributing updates and guide for writing a blog post

CONTRIBUTING-BLOG-POST.md

@@ -0,0 +1,149 @@
+# Contributing a Blog Post
+
+You are welcome to contribute a blog post for valkey.io.
+The contribution model is lightweight, transparent, and uses well-understood open-source processes.
+
+## Step 0: Setup
+
+Before you begin, it’s a good idea to setup an environment to write, test, and contribute your blog post.
+First, [fork the website repo](https://github.com/valkey-io/valkey-io.github.io), then clone the website to your local environment.
+The general workflow is to write your post locally in a branch, confirm that it looks the way you want , then contribute your changes as a pull request.
+
+The README has instructions on how to get up-and-running with Zola, the software used to build and test the website.
+
+## Step 1: Ideation
+
+The first step is to share your idea with the website maintainers through a GitHub issue.
+In the issue articulate what topic you want to write about and a general overview.
+The maintainers will evaluate your idea to understand if it fits into the site and doesn’t overlap with existing or in-process content.
+The maintainers will provide feedback as needed.
+
+Strictly speaking, you can forego this step and contribute a blog post directly as a pull request.
+However, if you don’t get the feedback from the maintainers you run the risk of doing work that doesn’t translate efficiently (or at all) into a blog post.
+
+## Step 2: Writing the post
+
+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).
+A few writing tips:
+
+1. Blog posts should be consumable in one setting.
+Aim for 500-1,200 words.
+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.
+4. [Valkey.io](http://valkey.io/) is not a commercial space; you can write about services and products as long as a) you’re not actively selling/promoting and b) the subject matter is directly related to the use of Valkey.
+    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.
+6. Have a call-to-action.
+What do you want your readers to do next after they finish your blog post? The call-to-action can be something like asking a users to contribute, try some sample code, or come to an event.
+You can even just invite users to reader related content.
+7. Speak for yourself.
+Blog posts are attributed to a person, not the project, so feel free to have opinions and write in the first (I) or second (you) grammatical person.
+Unless you have specific authority (and you probably don’t!), avoid speaking for groups of people.
+
+## Step 3: Write about yourself
+
+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.
+
+Each author needs to have a biography.
+The bio should be 1-2 paragraphs in length and should tell the reader who you are.
+Additionally, use the space to link yourself to the community: what makes you a person the reader should read and spend time on.
+If you already have a bio from a previous post, you don’t need to do a new one.
+
+It’s optional, but blog posts are even better when you have a bio *and* a photo.
+This personalizes the content further and conveys that you’re a real person.
+Attaching a photo isn’t always possible, so don’t fret if you don’t want to attach one.
+
+## Step 4: Put everything together
+
+[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:
+
+```text
++++
+# `title` is how your post will be listed and what will appear at the top of the post
+title=  "Using Valkey for mind control experiments"
+# `date` is when your post will be published.
+# For the most part, you can leave this as the day you _started_ the post.
+# The maintainers will update this value before publishing
+# The time is generally irrelvant in how Valkey published, so '01:01:01' is a good placeholder
+date= 2024-07-01 01:01:01
+# 'description' is what is shown as a snippet/summary in various contexts.
+# You can make this the first few lines of the post or (better) a hook for readers.
+# Aim for 2 short sentences.
+description= "It's become clear that people want to talk about Valkey and have been publishing blog posts/articles fervently. Here you'll find a collection of all the post I'm aware of in the last few weeks."
+# 'authors' are the folks who wrote or contributed to the post.
+# Each author corresponds to a biography file (more info later in this document)
+authors= [ "maury", "jacobim" ]
++++
+```
+
+You combine frontmatter with your writing into a single markdown file.
+The frontmatter must start at the first character on the first line of the file and your markdown goes below it.
+The name of the markdown file relevant.
+The path and general format is:
+
+```text
+/content/blog/yyyy-mm-dd-post-title-with-dashes-instead-of-spaces.md
+```
+
+The date portion (`yyyy-mm-dd`) is for internal organization purposes: this makes the blog post file easy to find and Zola ignores valid dates in this format.
+The *slug* (`post-title-with-dashes-instead-of-spaces` in the example) will form the URL of the blog post.
+So, the example would yield a blog post with a URL of `https://valkey.io/blog/post-title-with-dashes-instead-of-spaces/` .
+
+You’ll also need to create frontmatter for each author file.
+As an example:
+
+```text
++++
+# 'title' is how you want your name presented
+title= "Jacobim Mugatu"
+[extra]
+    # 'photo' is the path to the (optional) photo.
+    # the photo should be stored in `/assets/media/authors/`
+    # Try to get a medium resolution square-ish image (aim for around 500x500 but no more than 1000x1000)
+    photo= "/assets/media/authors/jacobim.jpg"
+    # 'github' is the (optional) link to your GitHub ID.
+    # For example if you can access your GitHub profile at https://github.com/octocat then you would use "octocat"
+    github= "octocat"
++++
+
+```
+
+Like with the blog post itself, following the frontmatter is the markdown biography.
+You can save the file to `/content/authors/YOUR-ID.md` , replacing `YOUR-ID` with some unique identifier (maybe align it with your name, GitHub ID, or an email address).
+The ID chosen should also match the `extra.authors`  in the post.
+So, for the example above it would be `/content/authors/jacobim.md` to match the string in the post’s frontmatter for `extra.authors` (`[ "maury", "jacobim" ]` ).
+
+At this point you should be able to test with `zola serve` as outlined in the README.
+If you made any syntax errors in your frontmatter the Zola process will display an error message.
+Proof read your post and bio(s), making any adjustments as needed.
+
+## Step 5: Make the contribution
+
+Now that you have a satisfactory blog post, you can make the contribution.
+Even if you’re used to making contributions to open source projects, Valkey uses a DCO so the process and commands might be a little different than what you’re used to.
+The CONTRIBUTING.md file goes over in detail what a DCO is and how to make a contribution with a DCO sign off.
+
+Keep in mind that you sign off your *commits* but GitHub checks for the sign offs when you make a *pull request;* it’s easier to fix a problem with the DCO sign-off before you make a pull request.
+The best practice is to run `git log` and ensure that every commit you’re about to contribute has `Signed-off-by:`  in the commit message, after confirming then run `git push origin ...`  .
+
+After your contribution is on your fork in GitHub, you can make a pull request to the website repo.
+Make sure to communicate your change fully in the body of the pull request.
+
+## Step 6: From contribution to publishing
+
+After your contribution is made, the website maintainers will review the post.
+They may have feedback for you and ask you to make changes.
+Once everyone is satisfied with the post, the maintainers will merge it into the `main` branch.
+The `main` branch of the repo represents the *future* state of all integrated changes before publishing.
+At this point, the maintainers make further changes to your post to properly schedule or link the post.
+Once this occurs, the maintainers will make move the changes into ‘production’ which will trigger a rebuild and publishing of the content website to [Valkey.io](http://valkey.io/)

CONTRIBUTING.md

@@ -1,26 +1,83 @@
 # Contributing Guidelines
 
-Thank you for your interest in contributing to Valkey website project. Whether it's a bug report, new feature, correction, or additional
-documentation, we greatly value feedback and contributions from the community.
+Thank you for your interest in contributing to Valkey website project.
+Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from the community.
 
 Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
 information to effectively respond to your bug report or contribution.
 
+## Developer Certificate of Origin
+
+We respect the intellectual property rights of others and we want to make sure
+all incoming contributions are correctly attributed and licensed. A Developer
+Certificate of Origin (DCO) is a lightweight mechanism to do that. The DCO is
+a declaration attached to every commit. In the commit message of the contribution,
+the developer simply adds a `Signed-off-by` statement and thereby agrees to the DCO,
+which you can find below or at [DeveloperCertificate.org](http://developercertificate.org/).
+
+```text
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the
+    best of my knowledge, is covered under an appropriate open
+    source license and I have the right under that license to
+    submit that work with modifications, whether created in whole
+    or in part by me, under the same open source license (unless
+    I am permitted to submit under a different license), as
+    Indicated in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including
+    all personal information I submit with it, including my
+    sign-off) is maintained indefinitely and may be redistributed
+    consistent with this project or the open source license(s)
+    involved.
+```
+
+We require that every contribution to Valkey to be signed with a DCO. We require the
+usage of known identity (such as a real or preferred name). We do not accept anonymous
+contributors nor those utilizing pseudonyms. A DCO signed commit will contain a line like:
+
+```text
+Signed-off-by: Jane Smith <[email protected]>
+```
+
+You may type this line on your own when writing your commit messages. However, if your
+user.name and user.email are set in your git configs, you can use `git commit` with `-s`
+or `--signoff` to add the `Signed-off-by` line to the end of the commit message. We also
+require revert commits to include a DCO.
+
+If you're contributing code to the Valkey project in any other form, including
+sending a code fragment or patch via private email or public discussion groups,
+you need to ensure that the contribution is in accordance with the DCO.
 
 ## Reporting Bugs/Feature Requests
 
 We welcome you to use the GitHub issue tracker to report bugs or suggest features.
 
 When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already
-reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
+reported the issue.
+Please try to include as much information as you can.
+Details like these are incredibly useful:
 
 * A reproducible test case or series of steps
 * Any modifications you've made relevant to the bug
 * Anything unusual about your environment or deployment
 
-
 ## Contributing via Pull Requests
-Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
+
+Contributions via pull requests are much appreciated.
+Before sending us a pull request, please ensure that:
 
 1. You are working against the latest source on the *main* branch.
 2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
@@ -29,7 +86,8 @@ Contributions via pull requests are much appreciated. Before sending us a pull r
 To send us a pull request, please:
 
 1. Fork the repository.
-2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
+2. Modify the source; please focus on the specific change you are contributing.
+If you also reformat all the code, it will be hard for us to focus on your change.
 3. Ensure local tests pass.
 4. Commit to your fork using clear commit messages.
 5. Send us a pull request, answering any default questions in the pull request interface.
@@ -38,18 +96,18 @@ To send us a pull request, please:
 GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
 [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
 
-
 ## Finding contributions to work on
-Looking at the existing issues is a great way to find something to contribute on. As Valkey projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
 
+Looking at the existing issues is a great way to find something to contribute on.
+As Valkey projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
 
 ## Code of Conduct
-PLACEHOLDER
-
+See [CODE_OF_CONDUCT.md] for more information.
 
 ## Security issue notifications
-PLACEHOLDER
+See [SECURITY.md] for more information.
 
 ## Licensing
 
-See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
+See the [LICENSE](LICENSE) file for our project's licensing.
+We will ask you to confirm the licensing of your contribution.

SECURITY.md

@@ -0,0 +1,6 @@
+## Reporting a Vulnerability
+
+If you believe you've discovered a security vulnerability, please contact the Valkey team at [email protected].
+Please *DO NOT* create an issue.
+We follow a responsible disclosure procedure, so depending on the severity of the issue we may notify Valkey vendors about the issue before releasing it publicly.
+If you would like to be added to our list of vendors, please reach out to the Valkey team at [email protected].