kudu git commit: [docs] Contributing to blog

[ab...@apache.org]

Repository: kudu
Updated Branches:
  refs/heads/master 74aa53f13 -> 7fee0ec15


[docs] Contributing to blog

Submitting blog posts are not straightforward, especially if someone
hasn't used Jekyll and/or Gerrit. This commit adds a "blog posts"
section to our contributing docs.

Change-Id: Ifd8ccae4b15b1ad8b679e0d2d8eabdf5fb5e3a09
Reviewed-on: http://gerrit.cloudera.org:8080/11940
Reviewed-by: Mike Percy <mp...@apache.org>
Tested-by: Attila Bukor <ab...@apache.org>


Project: http://git-wip-us.apache.org/repos/asf/kudu/repo
Commit: http://git-wip-us.apache.org/repos/asf/kudu/commit/7fee0ec1
Tree: http://git-wip-us.apache.org/repos/asf/kudu/tree/7fee0ec1
Diff: http://git-wip-us.apache.org/repos/asf/kudu/diff/7fee0ec1

Branch: refs/heads/master
Commit: 7fee0ec15384f8301866d45788c31a058116df04
Parents: 74aa53f
Author: Attila Bukor <ab...@apache.org>
Authored: Tue Nov 27 23:42:53 2018 +0100
Committer: Attila Bukor <ab...@apache.org>
Committed: Wed Nov 28 09:20:20 2018 +0000

----------------------------------------------------------------------
 docs/contributing.adoc | 97 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/kudu/blob/7fee0ec1/docs/contributing.adoc
----------------------------------------------------------------------
diff --git a/docs/contributing.adoc b/docs/contributing.adoc
index e22df56..bb2e4f6 100644
--- a/docs/contributing.adoc
+++ b/docs/contributing.adoc
@@ -456,3 +456,100 @@ Commits which may affect performance should include before/after `perf-stat(1)`
 See the
 link:https://github.com/apache/kudu/blob/master/docs/design-docs/doc-style-guide.adoc[Documentation Style Guide]
 for guidelines about contributing to the official Kudu documentation.
+
+== Blog posts
+
+=== Writing a post on the Kudu blog
+
+If you are using or integrating with Kudu, consider doing a write-up about your
+use case and your integration with Kudu and submitting it to be posted as an
+article on the Kudu blog. People in the community love to read about how Kudu
+is being used around the world.
+
+Consider checking with the project developers on the Kudu Slack instance or on
+mailto:dev@kudu.apache.org[dev@kudu.apache.org] if you have any questions about
+the content or the topic of a potential Kudu blog post.
+
+=== Submitting a blog post in Google Doc format
+
+If you don't have the time to learn Markdown or to submit a Gerrit change
+request, but you would still like to submit a post for the Kudu blog, feel free
+to write your post in Google Docs format and share the draft with us publicly
+on mailto:dev@kudu.apache.org[dev@kudu.apache.org] -- we'll be happy to review
+it and post it to the blog for you once it's ready to go.
+
+If you would like to submit the post directly to Gerrit for review in Markdown
+format (the developers will appreciate it if you do), please read below.
+
+=== How to format a Kudu blog post
+
+Blog posts live in the `gh-pages` branch under the `_posts` directory in
+Markdown format. They're automatically rendered by Jekyll so for those familiar
+with Markdown or Jekyll, submitting a blog post should be fairly
+straightforward.
+
+Each post is a separate file named in the following format:
+
+----
+YYYY-MM-DD-title-of-the-post.md
+----
+
+The `YYYY-MM-DD` part is the date which will be included in the link as
+`/YYYY-MM-DD`, then `title-of-the-post` is used verbatim. The words should be
+separated by dashes and should contain only lowercase letters of the English
+alphabet and numbers. Finally, the `.md` extension will be replaced with
+`.html`.
+
+The header contains the layout information (which is always "post"), the
+title and the author's name.
+
+----
+---
+layout: post
+title: Example Post
+author: John Doe
+---
+----
+
+The actual text of the blog post goes below this header, beginning with the
+"lead" which is a short excerpt that shows up in the index. This is separated
+by the `<!--more-\->` string from the rest of the post.
+
+=== How to check the rendering of a blog post
+
+Once you've finished the post, there is a command you can run to make sure it
+looks good called `site_tool` in the root of the `gh-pages` branch that can
+start up Jekyll and serve the rendered site locally. To run this, you need Ruby
+and Python to be installed on your machine, and you can start it with the below
+command.
+
+----
+$ ./site_tool jekyll serve
+----
+
+When starting, it will print the URL where you can reach the site, but it should
+be http://localhost:4000, or to reach the blog directly,
+http://localhost:4000/blog
+
+You should be able to see the title and lead of your post along with your name
+at the top of this page, and after clicking on the title or the "Read full
+post...", the whole post.
+
+=== How to submit a blog post
+
+To submit the post, you'll need to commit your change and push it to
+<<_contributing_patches_using_gerrit,Gerrit>> for review. If the post is deemed
+useful for the community and all comments are addressed, a committer can merge
+and publish your post.
+
+[TIP]
+====
+If you have a GitHub account, you can fork Kudu from
+https://github.com/apache/kudu and push the change to your fork too. GitHub will
+automatically render it on https://<yourname>.github.io/blog and you can link it
+directly on Gerrit.
+
+This way the reviewers can see that the post renders well without having to
+download it, which can speed up the review process.
+
+====