Skip to content

Latest commit

 

History

History
84 lines (68 loc) · 6.6 KB

contributing.adoc

File metadata and controls

84 lines (68 loc) · 6.6 KB
Raw

Contributor’s Guide

This guide will help new contributors use git and GitHub for Keycloak documentation submissions and suggestions.

Before you start, please take a look at our writing templates contained in the internal resources directory, which also describes each template file with information about when to use which. We are working to update our documentation to put procedural content, conceptual content, and reference content into separate .adoc files, and we kindly request that new contributions please use these templates.

There are two ways to start. The first is the easiest, but it is less flexible. The second is more powerful, but requires setting up. For either method, you must already have a GitHub account, as described in Join GitHub.

Simple and Infrequent Contributions (Method One)

This method is useful for quick fixes or simple additions.

  1. Find the file you want to edit in the GitHub web interface.

  2. Click the file name to open it in GitHub.

  3. Click the edit icon near the top right of the page contents. The icon looks like a pencil.

  4. Make your edits.

  5. Enter a title and description of your changes in the Commit Changes section at the bottom of the page. Enter enough detail for reviewers to know what you have changed and why.

  6. Select Create a new branch for this commit and start a pull request.

  7. Click Commit changes.

Larger and Sustained Contributions (Method Two)

This method is useful for any type of contribution, but necessary for larger and more complex ones. If you expect to participate often, this is the recommended method.

Initial Setup

You only need to perform these tasks once, when preparing to contribute.

  1. Fork the Keycloak documentation repository. This will create your own version of the repository which you can find at https://github.com/{yourusername}/keycloak-documentation where {yourusername} is the username you created in GitHub.

  2. Install git on your local machine. The procedure differs by operating system as described in Installing Git. Follow up with initial Git setup tasks, as described in First Time Git Setup.

  3. Clone from your fork to create a copy on your local machine and then navigate to the new directory by entering the following from the command line on your local machine:

    $ git clone https://github.com/{yourusername}/keycloak-documentation
$ cd keycloak-documentation

  4. Add a git remote to your local repository to link to the upstream version of the documentation. This makes it easier to update your fork and local version of the documentation.

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

  5. Check your settings.

    $ git remote -v
origin	https://github.com/{yourusername}/keycloak-documentation.git (fetch)
origin	https://github.com/{yourusername}/keycloak-documentation.git (push)
upstream	https://github.com/keycloak/keycloak-documentation (fetch)
upstream	https://github.com/keycloak/keycloak-documentation (push)
    Note
    		 It is possible to clone using SSH so you don’t have to enter a username/password every time you push. Find instructions at Connecting to GitHub with SSH and Which Remote URL Should I Use. When using SSH, the origin lines will appear like this: [email protected]:{yourusername}/keycloak-documentation.git

Typical Workflow for Keycloak Documentation Contributions

When contributing, follow this procedure. Enter commands from the command line on your local machine in the keycloak-documentation directory created earlier when cloning the repository.

  1. Enter git checkout main to checkout the main branch locally.

  2. Enter git fetch upstream to download the current files from the upstream repository.

  3. Enter git rebase upstream/main to update your cloned branch on your local machine with the most current content from the upstream repository.

  4. Enter git push origin main to update your fork in GitHub with the most current content from the upstream repository.

  5. Enter git checkout -b {branchname} where you create a {branchname} that describes the work you are about to do.

  6. Make your changes

  7. (Optional) Enter git status now or at any time to see what branch you are on, what files you have changed, and whether those files are staged to be committed.

  8. Enter git add -A to stage your changes to the commit you are about to make.

  9. Enter git commit -m 'KEYCLOAK-XXXX include meaningful information about changes' where KEYCLOAK-XXXX refers to the Jira issue being fixed in this commit (if any) and where you add a short sentence that clearly describes what the commit contains.

  10. Follow the steps in the README to create a test build locally and confirm that your changes look correct. Make more changes and repeat steps to here, as needed.

  11. Enter git push origin {branchname} to push your changes to your fork in GitHub.

  12. Use the GitHub web interface to create a pull request. First, navigate to your branch in the web UI and click Compare. This will show you a diff of the changes. Examine them one more time. If necessary, make more changes locally and repeat the steps to here. When you are ready, click Create a pull request. Enter a title and a description with enough detail for reviewers to know what you have changed and why. Click Submit.

  13. Wait. The documentation team will usually review pull requests within a few days. Often suggestions and changes are requested of you to help the contribution better fit within the style guidelines for the project or to fill in information that may have been missed. If this happens, repeat the steps from making your changes to git push origin {branchname}. No need to create another PR as the existing one will be updated automatically.

Once the PR has been merged or rejected, you can remove your feature branch {newbranchname} from both the remote fork and your local machine. GitHub provides a button for removing from the fork in the UI of the PR once it is merged. Remove from your local machine with git branch -d {branchname}.