Skip to content

Making changes to published guides

Jump to bottom
Laura Cowen edited this page Dec 1, 2017 · 9 revisions

(Written in Markdown but needs converting to Asciidoc for ease of editing.)

Found a mistake or something that could be clearer in one of the published guides? Here's how to make and publish a change.

Each Open Liberty guide lives in its own GitHub repository. For example, the Creating a RESTful web service guide lives in the openliberty/guide-rest-intro repository. In the repository is both the text of the guide (in the README.adoc) and the sample code (in the start and finish directories).

Editing guides

  1. On the GitHub.com website, fork the repository of the guide you want to edit:
  2. Log into your GitHub.com account.
  3. Find the repository for the guide (I'm using the REST guide as an example here).
  4. At the top of the page, click the Fork button. This creates a copy of the repository in your account. (Find out more about forks.)
  5. Clone the forked repository to your machine. In the terminal: git clone https://github.com/lauracowen/guide-rest-intro.git (replace this URL with the URL you get when you click the green Clone or download button on the repository's webpage). You should now have a directory called guide-rest-intro in your current location (/Users/laura/github/openliberty/openliberty.io/src/main/content/guides).
  6. In the terminal: cd guide-rest-intro. This is the guide. The README.adoc file contains the guide text.
  7. Edit the README.adoc file using Asciidoc.
  8. Test your changes.

Testing your guide changes

What? Who? How?
The guide transforms to HTML correctly without any errors only. Author. Install and run Asciidoctor
The guide transforms to HTML correctly and the content looks right on the Open Liberty website. Author or pull request reviewer. Install and run a local test website

Ideally, authors should take the second approach but the first approach is quicker to work with whilst editing, and there's slightly less setup involved.

Publish your changes

When you're happy with how your changes look in the test site, you can create a pull request to push them back to the main GitHub repository.

  1. In a terminal in the guide you've been changing (e.g. /Users/laura/github/openliberty/openliberty.io/src/main/content/guides/guide-rest-intro), check the changes: git status The README.adoc file should be listed as 'modified'.
  2. Add the file to be committed: git add README.adoc
  3. Commit the file in your local git version control: git commit then enter a description (or list) of why you made the changes (the changes themselves can be easily seen; a good commit message describes why). If you can't handle the default text editor, instead use the command git commit -m type_your_commit_message_here but you can only provide a single line this way.
  4. Create a new branch in your account: git checkout -b branch_name (where branch_name is your initials and a brief name for the branch; e.g. ljc_fixedtypos).
  5. Push the changes to GitHub: git push origin ljc_fixedtypos The file is now updated in your fork (copy) of the guide repository on GitHub.com. Click the Branch button on the repository page to switch from master to your new branch to see the changes.
  6. Create a pull request to the guide's repository, e.g. openliberty/guide-rest-intro:
  7. On the repository page in your account (eg https://github.com/lauracowen/guide-rest-intro), click New Pull Request.
  8. Make sure the settings are base fork: OpenLiberty/guide-rest-intro, base: master, head fork: lauracowen/guide-rest-intro, base: ljc_fixedtypos.
  9. Check that the correct file and changes are included in the pull request, then enter a description of the changes you've made in the pull request.
  10. Add a reviewer to the pull request.
  11. Submit the pull request.
  12. Optionally, link your pull request to the issue(s) that it resolves. Feel free to create new issues as appropriate.

The reviewer will then be notified to review the changes. They might ask you to make some modifications. If they do, just make your changes locally and go through the git add, git commit, git push steps again (use the same branch). I think the PR is automatically updated to include the changes...[check this]. When the reviewer is happy, they'll merge your changes into the master branch of the guide. Next time the guide is built, the changes will be incorporated into the live website at http://openliberty.io/guides. And you're done!

Clone this wiki locally