Skip to content

Latest commit

 

History

History
85 lines (69 loc) · 6.5 KB

contributing.adoc

File metadata and controls

85 lines (69 loc) · 6.5 KB

Contributor’s Guide

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

Before you start, check out our writing templates, which are contained in the internal resources directory, This directory also describes each template file and when to use that template. We are working to update our documentation to put procedural content, conceptual content, and reference content into separate .adoc files, and we request that new contributions 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 repository. This will create your own version of the repository which you can find at https://github.com/{yourusername}/keycloak 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
$ cd keycloak/docs/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

  5. Check your settings.

    $ git remote -v
origin	https://github.com/{yourusername}/keycloak.git (fetch)
origin	https://github.com/{yourusername}/keycloak.git (push)
upstream	https://github.com/keycloak/keycloak (fetch)
upstream	https://github.com/keycloak/keycloak (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.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 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.

    1. Make sure your changes only affect docs/documentation directory, or you are sure about the changes outside of that package

  9. Enter git commit --signoff --message '<message>' where message is build as described in general contribution guide

  10. Follow the steps in the documentation 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}.