Making changes to published guides

Editing guides (repeat for each guide)

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:
9. At minimum, run Asciidoctor against the README.adoc file to generate the HTML version. Doing this checks that the file transforms to HTML and none of the tagging is broken. But the formatting and style won't look exactly like the end result.
10. Ideally, check the guide in a local test website. Doing this shows you the formatting and style of the end result.

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!