Writing and publishing blog posts on the OpenLiberty.io blog

• Writing and publishing blog posts on the OpenLiberty.io blog
  • Blog sites
  • Authors: creating a new blog post
  • Editors: editing and publishing a post
  • Authors and Editors: updating a published post
  • Troubleshooting Asciidoc
  • Troubleshooting GitHub workflow

Blog sites

• full draft site Contains all draft content (draft branches) of the site

• blog-draft site Contains only the blog portion of the draft content (draft branch) of the site

• full staging site Contains all staging content (staging branches) of the site

• blog-staging site Contains only the blog portion of the staging content (staging branch) of the site

• production site Contains all production content (prod branch) of the site

Authors: creating a new blog post

These steps are to be completed by the author of the blog post.

1. Create an issue for the blog post. This is to help the editors track the progress of the post.

   • All blog posts except release blog posts

     Create an issue. In the description, give a simple outline of the purpose of the blog post. If there is a specific date by which the post must be available, mention that in the description too.

   • GA and beta release blog posts (Open Liberty GA and beta release announcements only)

     Create a new issue using the Open Liberty release notes issue template. Make sure to select each task in the issue as you complete it to show progress.

2. Clone the repo and create a branch off the default prod branch. From the prod branch, run: git checkout -b branch_name, where branch_name is a name you give your new branch.

   Do all your editing in this branch so that the blog editors can make any necessary edits directly in the branch before publishing your post.

3. Create your blog post using Asciidoc markup (use an editor such as VSCode with the Asciidoc plugin):

   • Blog post (probably what you're doing)

     Copy the post-single-author.adoc file (or post-multiple-authors.adoc for multiple authors) to the posts directory and rename the file using the format YYYY-MM-DD-post-title.adoc, where the date represents the expected publication date (e.g. 2021-11-21-open-liberty-is-awesome.adoc).

     Place any images in img/blog. Add a border to screenshots to neaten the edges.

   • GA release blog post (Open Liberty GA release announcements only)

     Copy the ga-release-post.adoc file to the posts directory and rename the file using the format YYYY-MM-DD-post-title.adoc, where the date represents the expected publication date and the end of the file name is the release version number without periods (e.g. 2021-11-21-open-liberty-is-awesome-210011.adoc).

     Place any images in img/blog. Add a border to screenshots to neaten the edges.

     Ensure that the Asciidoc tags (e.g. // tag::intro[] and // end::intro[]) in the template are retained around the relevant parts of the release post. These Asciidoc tags will be used to build alternative versions of the post content.

   • Beta release blog post (Open Liberty beta release announcements only)

     Copy the beta-release-post.adoc file to the posts directory and rename the file using the format YYYY-MM-DD-post-title.adoc, where the date represents the expected publication date and the end of the post title is the beta release version number without periods or hyphens (e.g. 2021-11-21-new-awesomeness-coming-soon-210012beta.adoc).

     Place any images in img/blog. Add a border to screenshots to neaten the edges.

   • Third-party blog post (externally hosted posts only)

     Copy the third-party-post.adoc file to the posts directory and rename the file using the format YYYY-MM-DD-post-title.adoc, where the date represents the expected publication date (e.g. 2021-11-21-open-liberty-is-awesome.adoc).

4. If you are not employed by IBM, in at least one of your commits, sign off the commit using the Developer Certificate process.

5. When you have finished the post, check that it renders correctly. If you have a preview function in your editor, use that (eg the Asciidoc plugin in VSCode). Otherwise, you can check that GitHub renders it properly when you push to GitHub in the next step.

6. Push the file to GitHub, then create a pull request (PR) into the draft branch.

   Link the PR to the issue you created in Step 1. Anyone can review/approve the PR before you merge it.

   (If you've been working in a fork for some reason, create a feature branch [see Step 2] and push your changes to the feature branch, then create a PR to the draft branch from there.)

   If you find there are a load of merge conflicts at this stage, see Troubleshooting GitHub workflow.

7. All the builds and deployments of non-prod sites run on IBM Cloud and build automatically whenever a PR is merged into their respective branch. These builds are private and, therefore, their detailed build/deploy progress can't be tracked. However, if you have access to the Slack channel for draft site or the Slack channel for staging site, you can at least track when the builds start and finish.

8. When the build is finished, check that the blog renders correctly on either the blogs-draft site or the full draft site.

   In addition to the existing full draft site we now have a blogs-draft site, which contains only the blog content, allowing it to build and deploy much quicker. However, since this site contains only the blog content, any links to other parts of openliberty.io will not resolve. In general, use the blogs-draft site to review content because it updates much quicker than the full site. However, if you need to review content that links to pages on openliberty.io that are not in the blogs, use the full draft site.

   If you see any problems , such as formatting issues or typos, resolve them first in your branch. Then, create another PR into draft branch, link the PR to the issue again, and get the PR merged. Wait for IBM Cloud to rebuild blogs-draft site or draft site and verify the change.

9. When you're happy with the post:

   • Create a PR from your branch (not from the draft branch) to the staging branch.
   • Link the PR to the issue.
   • In the PR, provide a link to your post on the blogs-draft site or draft site.
   • Ideally, also paste a screenshot of the entire blog post page as this will allow reviewers to see the rendered post content even while the sites are innaccessible (e.g. redeploys).
   • Add @GraceJansen, as well as your technical reviewer and any other reviewers to get their final approval for both content and format.

10. The editors will now review and edit the post. Please respond to any questions they ask or suggestions they make. Their aim is to make the post readable and useful to its target audience.

11. If you need to make changes based on review comments, as before:

    • Make any changes in your feature branch
      • The updates that you make to your branch for the draft PR will be automatically picked up by your staging PR; there is no need to update it.
    • Create a PR to the draft branch
    • Link the PR to the issue
    • Merge the PR
    • Once the site rebuilds, check that everything is correct on the blogs-draft site or draft site.

12. Get reviewers to review the updates in your new PR.

You're done! The editors will handle the rest.

Please note that if you have a specific date in mind that you want this blog to be published by, we need a final draft of the blog to be ready for editing in the draft repo a minimum of two weeks prior to the desired publish date.

Editors: editing and publishing a post

These steps are completed by the editors of the blog. As editor, you might ask questions or make suggestions to the author of the post. You might also make edits directly in the post to prepare it for publishing.

1. Review the post on the blogs-draft site or draft site as linked from the issue.

   Ask the author to make changes by adding review comments to the PR.

   For edits such as punctuation, formatting, highlighting, adding SEO details, or larger changes discussed with the author, the editor can make the edits directly in the author's branch and push the changes to draft branch, which automatically rebuilds the blogs-draft site and draft site where you can verify the changes.

   To check out the author's branch locally: git fetch origin then git checkout -b branch_name origin/branch_name, which creates a new local branch that's linked to their remote branch. When you've made changes, push them back to origin/branch_name.

2. When a publishing date has been decided:

   • Check that the post looks fine.

   • Check that the author's details and the SEO details, including front matter, the title, and the filename slug, are appropriate for the post.

   • If necessary, rename the file with the planned publication date.

3. Add blog tags to the blog post:

   a. In the staging branch, update the blogs_tags.json file by adding the slug of the blog post (the file name without the date part or the .adoc) to the start of the posts array (1-2 entries per line) for each appropriate tag. You can do this in the web UI editor as long as you're careful with the syntax. This is done in staging to reduce the number of merge conflicts in the draft branch later. However, you should backport this change to draft once it is verified on staging.

   b. Merge the changes to staging branch. You can do this in advance of the post being ready (as long as the post's file name doesn't change). It's fine if this file gets merged to prod earlier than the post itself.

4. On the day of publication (or the day before):

   a. Approve the PR.

   b. Merge the PR into staging.

5. IBM Cloud will automatically rebuild the blogs-staging site and staging site. If you have access, you can track the progress in the Slack channel.

6. When the build has finished, check to make sure the blog with its blog tags render correctly on the blogs-staging site or staging site. The latter includes the entire site, while the former just has the blog content. If you need to verify links to other parts of the site (outside of the /blogs/ content) then you'll need to wait for the full staging site to build.

   This is the final check before the post is published live on the production site.

   If there are any problems with the content in the staging branch, you must resolve them quickly or revert the PR (the post must not stay in staging longer than a couple of hours or you risk someone accidentally publishing it for you).

   Make any changes in the author's branch, and push to both draft and staging.

7. To publish the post, create a PR from staging branch to prod branch and add the author of the post or another editor as approver.

8. When the PR is approved, merge it into prod.

9. Rebuild the production site from the IBM Cloud console.

   When the build has finished, check that the post looks as expected on openliberty.io/blog.

   If the post's file name uses a future date, the post will not exist on the production site until at least that date and the production site has been rebuilt.

10. When the post is published, and any changes you made are in all three branches (draft, staging, and prod), delete the author's branch.

You've published a post!

Authors and Editors: updating a published post

If a published post on openliberty.io/blog contains an error or needs updating in any way, anyone can create a PR to get it fixed.

1. As when creating a new post (see above), clone the blogs repo and create a new branch based on the prod branch. You will do all your work in this branch.

2. Open the file in an editor (e.g. VSCode with the Asciidoc plugin) and make any changes needed.

3. If the blog tags need correcting, update the blogs_tags.json file. If you add new tags, make sure to add the blog post's slug to the beginning of the posts arrays (1-2 entries per line) for each tag.

4. Create a PR from your branch to the draft branch. After the PR is merged, wait for IBM Cloud to rebuild the blogs-draft site or full draft site. If you have access to this Slack channel, you can use it to track build/deploy progress. Verify the changes on the blogs-draft site or draft site.

   Make any changes in your branch, then push to the draft branch again and verify the changes after rebuild.

5. Create a PR from your branch to staging branch (not from draft branch) and add @GraceJansen as reviewer. You can create this PR at any point because any new changes you make in your branch are automatically added to the PR.

6. When the PR is approved, the editor will merge it the staging branch, causing IBM Cloud to automatically kick off a build of both the blogs-staging site and staging site, which you can use to verify the changes look correct.

7. The approver will then create a PR from staging to prod, then merge and rebuild the production site from the IBM Cloud console to publish the updates on the openliberty.io/blog.

Troubleshooting Asciidoc

• Certain characters (eg apostrophe ' ) in the main heading are displayed incorrectly. To fix, escape with a backslash (\). eg = Minimise turnaround times with Open Liberty\'s dev mode

• Syntax highlighting in code snippets isn't displaying correctly. To fix, make sure you've put your code snippet in source tags:

  [source,xml]
  ----
  your code snippet here
  ----
  

  Where xml is the language used in your code snippet. See the supported list of languages. If your languages isn't supported (eg a Dockerfile or shell script), remove the language attribute: [source].

• Screenshot edges are untidy. To fix, place the custom border attribute on the line above the image tag for all screenshots:

  [.img_border_light]
  image::/img/blog/pipeline-code-on-jenkins.png[Pipeline code directly on Jenkins,width=70%,align="center"]
  

  If the screenshot has a dark background, use [.img_border_dark] instead. The aim is to harden the edges of the screenshot, not to create a strong visible border line.

See also:

• Asciidoc quick syntax
• Asciidoc user manual (more detailed)

Troubleshooting GitHub workflow

When you create a PR from your feature branch to the draft branch, you might find that you have some conflicts. If you use the Web UI to resolve the conflicts and commit those changes, you will find that GitHub has merged everything from the draft branch into your feature branch, including other people's drafts. You must not try to merge all those changes to staging or else you'll end up publishing a load of half-finished work. Instead, create a new feature branch off prod and use the git cherry-pick command to select only the files that you want to publish from the draft branch. Then use this new feature branch to create the PR to staging.

For more about the git cherry-pick command, see StackOverflow (or search online for more help). You might need some practice to get the hang of it but it's a useful skill to acquire if you do much in GitHub.