created contributors guide and edited existing related files
This commit is contained in:
parent
736429a86e
commit
ebc668dbea
3 changed files with 90 additions and 14 deletions
|
@ -6,6 +6,12 @@ Open Source Identity and Access Management for modern Applications and Services.
|
|||
For more information about Keycloak visit [Keycloak homepage](http://keycloak.org) and [Keycloak blog](http://blog.keycloak.org).
|
||||
|
||||
|
||||
Contributing to Keycloak Documentation
|
||||
--------------------------------------
|
||||
|
||||
See our [Contributor's Guide](internal_resources/contributing.adoc). The directory also includes a set of templates and other resources to help you get started.
|
||||
|
||||
|
||||
Building Keycloak Documentation
|
||||
-------------------------------
|
||||
|
||||
|
|
|
@ -3,14 +3,18 @@ Keycloak Documentation Guidelines
|
|||
|
||||
This folder contains guidelines for writers.
|
||||
|
||||
Templates
|
||||
------
|
||||
Contributor's Guide
|
||||
-------------------
|
||||
|
||||
Which template should you use for your new content?
|
||||
See our [Contributor's Guide](contributing.adoc) to learn how the procedure for making contributions to documentation.
|
||||
|
||||
Templates
|
||||
---------
|
||||
|
||||
We have templates that we you use for your new content. When:
|
||||
|
||||
* I want to do X
|
||||
* Use the [Task Template](template_task.adoc)
|
||||
* Once you have mastered the task template you can use the [brief task template](template_task_brief.adoc) to create your content.
|
||||
* Use the [brief task template](template_task_brief.adoc). The [detailed task template](template_task.adoc) has a wealth of resources and tips that you may find useful.
|
||||
* I want to understand X
|
||||
* Use the [Concept Template](template_concept.adoc)
|
||||
* I want to know X
|
||||
|
@ -19,12 +23,4 @@ Which template should you use for your new content?
|
|||
Styles
|
||||
------
|
||||
|
||||
When writing content we use the following style guides in order:
|
||||
|
||||
1. IBM Style Guide (printed)
|
||||
2. [IBM DeveloperWorks Editorial Style Guide](https://www.ibm.com/developerworks/library/styleguidelines/)
|
||||
3. [Red Hat Corporate Style](http://brand.redhat.com/elements/)
|
||||
4. [RH-SSO Style Guide](styleguide.adoc)
|
||||
5. [RH-SSO Terms and Conventions](terms_conventions.adoc)
|
||||
6. [Red Hat Glossary of Terms and Conventions](http://ccs-jenkins.gsslab.brq.redhat.com:8080/job/glossary-of-terms-and-conventions-for-product-documentation-branch-master/lastSuccessfulBuild/artifact/index.html)
|
||||
7. [RH-SSO Screenshot Guidelines](screenshots.adoc)
|
||||
When writing content we use the IBM Style Guide.
|
74
internal_resources/contributing.adoc
Normal file
74
internal_resources/contributing.adoc
Normal file
|
@ -0,0 +1,74 @@
|
|||
[[contributing]]
|
||||
= Contributor's Guide
|
||||
|
||||
This guide will help new contributors use `git` and GitHub for Keycloak documentation submissions and suggestions.
|
||||
|
||||
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 link:https://github.com/join[Join GitHub].
|
||||
|
||||
[[simple]]
|
||||
== Simple and Infrequent Contributions (Method One)
|
||||
|
||||
This method is useful for quick fixes or simple additions.
|
||||
|
||||
. Find the file you want to edit in the GitHub web interface.
|
||||
. Click the file name to open it in GitHub.
|
||||
. Click the edit icon near the top right of the page contents. The icon looks like a pencil.
|
||||
. Make your edits.
|
||||
. 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.
|
||||
. Select *Create a new branch for this commit and start a pull request*.
|
||||
. Click *Commit changes*.
|
||||
|
||||
[[sustained]]
|
||||
== 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.
|
||||
|
||||
[[initialsetup]]
|
||||
=== Initial Setup
|
||||
|
||||
You only need to perform these tasks once, when preparing to contribute.
|
||||
|
||||
. Fork the link:https://github.com/keycloak/keycloak-documentation[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.
|
||||
. Install `git` on your local machine. The procedure differs by operating system as described in link:https://git-scm.com/book/en/v2/Getting-Started-Installing-Git[Installing Git]. Follow up with initial Git setup tasks, as described in link:https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup[First Time Git Setup].
|
||||
. 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:
|
||||
[source,bash]
|
||||
----
|
||||
$ git clone https://github.com/{yourusername}/keycloak-documentation
|
||||
$ cd keycloak-documentation
|
||||
----
|
||||
. 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.
|
||||
[source,bash]
|
||||
----
|
||||
$ git remote add upstream https://github.com/keycloak/keycloak-documentation
|
||||
----
|
||||
. Check your settings.
|
||||
[source,bash]
|
||||
----
|
||||
$ 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 link:https://help.github.com/articles/connecting-to-github-with-ssh/[Connecting to GitHub with SSH] and link:https://help.github.com/articles/which-remote-url-should-i-use/[Which Remote URL Should I Use]. When using SSH, the origin lines will appear like this:
|
||||
`git@github.com:{yourusername}/keycloak-documentation.git`
|
||||
|
||||
[[workflow]]
|
||||
=== 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.
|
||||
|
||||
. Enter `git checkout master` to checkout the master branch locally.
|
||||
. Enter `git rebase upstream/master` to update your cloned branch and your fork with the most current content from the upstream repository.
|
||||
. Enter `git checkout -b {branchname}` where you create a `{branchname}` that describes the work you are about to do.
|
||||
. Make your changes
|
||||
. (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.
|
||||
. Enter `git add -A` to stage your changes to the commit you are about to make.
|
||||
. Enter `git commit -m 'KEYCLOAK-XXXX include meaningful information about changes'` where `KEYCLOAK-XXXX` refers to the link:https://issues.jboss.org/projects/KEYCLOAK/issues[Jira issue] being fixed in this commit (if any) and where you add a short sentence that clearly describes what the commit contains.
|
||||
. Follow the steps in the link:https://github.com/keycloak/keycloak-documentation/blob/master/README.md[README] to create a test build locally and confirm that your changes look correct. Make more changes and repeat steps to here, as needed.
|
||||
. Enter `git push origin {branchname}` to push your changes to your fork in GitHub.
|
||||
. 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*.
|
||||
. 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}`.
|
Loading…
Reference in a new issue