= RH-SSO GitHub and GitLab instructions

== Set up procedures
You only need to perform the following sets of procedures one time to fork, clone, and configure the Keycloak and RH-SSO repositories.

=== Fork, clone, and configure the Keycloak repositories

. Change the directory to the GitHub folder:

 $ cd github

. Click the Fork button in the keycloak-documentation repository to create your own remote GitHub instance.

. Clone your keycloak-documentation instance:

 $ git clone git@github.com:<username>/keycloak-documentation.git

. Navigate to your local github/keycloak-documentation repository folder and add the upstream Keycloak remote repository: 

 $ git remote add -f upstream git@github.com:keycloak/keycloak-documentation.git

. If you need to cherry-pick changes to another repository (such as keycloak-documentation-prod) from this one, you must add that remote repository:

 $ git remote add -f <KEYCLOAK_OTHER_REPO> git@github.com:keycloak/<KEYCLOAK_OTHER_REPO>.git

. Ensure that the remote repositories were added:

 $ git remote -v

You should see something like this for GitHub: 
----
keycloak-documentation    git@github.com:keycloak/keycloak-documentation.git (fetch)
keycloak-documentation    git@github.com:keycloak/keycloak-documentation.git (push)
origin    git@github.com:jmalloy/keycloak-documentation-prod.git (fetch)
origin    git@github.com:jmalloy/keycloak-documentation-prod.git (push)
upstream    git@github.com:keycloak/keycloak-documentation-prod.git (fetch)
upstream    git@github.com:keycloak/keycloak-documentation-prod.git (push)
----

=== Fork, clone, and configure the RH-SSO repositories

. Change the directory to the GitLab folder:

 $ cd gitlab

. Click the Fork button in the GitLab RH-SSO repository to create your own remote GitLab instance.

. Clone your RH-SSO instance:

 $ git clone git@gitlab.cee.redhat.com:<username>/<RH_SSO_REPO>.git

. Change the directory to the guide repository folder:

 $ cd <guide-name>

. Add the RH-SSO repository as the upstream remote repository:

 $ git remote add -f upstream git@gitlab.com:red-hat-single-sign-on-documentation/<RH_SSO_REPO>.git

. Ensure that the remote repositories were added:

 $ git remote -v

You should see something like this for GitLab:
----
origin	git@gitlab.cee.redhat.com:jmalloy/doc-release-notes.git (fetch)
origin	git@gitlab.cee.redhat.com:jmalloy/doc-release-notes.git (push)
upstream	git@gitlab.cee.redhat.com:red-hat-single-sign-on-documentation/doc-release-notes.git (fetch)
upstream	git@gitlab.cee.redhat.com:red-hat-single-sign-on-documentation/doc-release-notes.git (push)
----

== Subsequent updates
Follow these steps for any subsequent documentation changes needed.

=== GitHub process

The process starts with the upstream side, which for RH-SSO is in a GitHub repository (keycloak-documentation).

. In a Terminal window, navigate to your cloned GitHub Keycloak repository:

 cd github
 cd keycloak-documentation

. Fetch the latest content from upstream:

 git fetch upstream

. Check out a topic branch to work in:

 git checkout -b BRANCH_NAME upstream/master

IMPORTANT: Do NOT forget to put the ‘upstream/master’ at the end of the command. Otherwise you might be working with the wrong content.

. Do work / make edits.

. Check the status to make sure the changed files look correct:

 git status

. Change to the guide directory:

 cd <guidename>

. Run the python script:

 python gitlab-conversion.py
+
It transforms any variables used and creates the modified files in the `target/` directory.

. Run the ./buildGuide.sh script to check for errors and and verify document is correct.

. Add each of the new or updated files:

 git add <FILE_NAME>

. Check the status once again to make sure all updated files are staged for the commit:

 git status

. Commit the changes:

 git commit -m "<Your commit message>"

. Push the changes to your forked repository, in a branch of the same name:

 git push origin HEAD

. In the GitHub repo: Submit a new pull request for this content change. Carefully review the changes to make sure they are correct.

. In the GitHub repo: Accept the pull request.

. For changes to 7.1 content, xref:cherry_picking[cherry-pick this commit to the keycloak-documentation-prod repository, 7.1.x branch].

[[cherry_picking]]
=== Cherry-picking to the 7.1 repository

To cherry-pick a change from the keycloak-documentation repository (master branch) to the keycloak-documentation-prod repository (7.1.x branch), complete the following steps:

. Change the directory to the keycloak-documentation-prod directory: 

 cd ../../
 cd keycloak-documentation-prod

. Fetch the latest keycloak-documentation-prod content:

 git fetch upstream

. Check out a topic branch to work in:

 git checkout -b <branch-name> upstream/7.1.x

. Fetch the latest keycloak-documentation content:

 git fetch keycloak-documentation

. Cherry-pick the change made to keycloak-documentation to keycloak-documentation-prod:

 git cherry-pick <commit_ID>
+
NOTES:

* Do not cherry-pick any merges; cherry-pick commits only!
* If you have multiple commits to cherry-pick, repeat this step to add the other commits, and then proceed to the next step when you are finished adding all the commits.

+
HINT: To easily obtain the commit ID: In a web browser, go to the keycloak-documentation repo and locate the commit. Then open the commit in a new browser tab, and copy the commit ID  from the URL (for example: \https://github.com/keycloak/keycloak-documentation/commit/e99645fbbce4f56676e22d5f86e34dca913fca32). 
. git log (Make sure that commit is the first one listed; press q to quit and return to the command line)
. git status (Make sure there are no conflicts. If there are conflicts, you must resolve them. “nothing to commit; working directory clean” is the desired message.) 
. Push the cherry-pick:

 git push origin HEAD

. Submit a new pull request for the 7.1.x branch for this content change. Carefully review the changes to make sure they are correct.

. Accept the pull request.

. Ensure the guide builds successfully from the keycloak-documentation-prod repository. In keycloak-documentation-prod, change to the guide directory:

 cd <guidename>

. Run the python script:

 python gitlab-conversion.py
+
It transforms any variables and creates the modified files in the `target/` directory.

. Run the ./buildGuide.sh script to check for errors and and verify document is correct. Continue with instructions for GitLab side of the process.

=== GitLab process

The downstream process uses GitLab to produce the product docs. 

To pull the changes over to the product docs, complete the following steps:

. Navigate to your cloned GitLab RH-SSO repository folder: cd ../../../; cd gitlab; cd <guidename>

. Fetch the latest RH-SSO upstream content:

 git fetch upstream

. Check out a topic branch to work in:

 git checkout -b <BRANCH_NAME> upstream/master

. Copy the files from the cloned GitHub keycloak-documentation-prod <guidename> `target/` directory into this folder. 
NOTE: Do not delete the files first. If you get a message about replacing or merging files, select *Replace* or *Merge* and select the check box for all subsequent files.

. Check the status to view the changed and new files:

 git status

. Add the updated or new files:

 git add <FILE_NAME>

. Check the status once again to make sure all updated files are staged for the commit:

 git status

. Commit the changes:

 git commit -m "<Your commit message>"

. Push the commit to your forked repository in a branch of the same name as your topic branch:

 git push origin HEAD

. In the GitLab repo: Submit the merge request. Carefully review the changes to make sure they are correct.

. In the GitLab repo: Accept the merge request. This kicks off the Preview build in Pantheon.

. Go to the https://pantheon.cee.redhat.com/#/titles/red-hat-single-sign-on[Pantheon site] to view the built guide in Preview.

. When ready, xref:push_to_stage[push to 7.1.x (Stage)].
NOTE: This step does not have to be done with every merge to Preview, only when you want to push to Stage, which is the step before publishing live to the Customer Portal. 

[[push_to_stage]]
==== Push to Stage

. In the GitLab project repository for the guide, click *Branches*.

. For the 7.1.x branch, click *Compare*.
. Click the arrows to the left of the compare to switch the basis of comparison. 
. Ensure that everything looks correct.
. Click *+ Merge Request*.
. Submit the merge request. Carefully review the changes to make sure they are correct.

. Accept the merge request. This kicks off the build in Pantheon on Stage.

. Go to the https://pantheon.cee.redhat.com/#/titles/red-hat-single-sign-on[Pantheon site] to view the built guide on Stage.