|
1 | | -# Keycloak Community |
| 1 | +# Keycloak Client libraries |
2 | 2 |
|
3 | | -Keycloak is an Open Source Identity and Access Management solution for modern Applications and Services. |
| 3 | +Keycloak is an Open Source Identity and Access Management solution for modern Applications and Services. Keycloak-client is a set of Java libraries, which can be used in the client applications to invoke Keycloak server public |
| 4 | +APIs. |
4 | 5 |
|
5 | | -## Building and working with the codebase |
6 | | - |
7 | | -Details for building from source and working with the codebase are provided in the [building and working with the code base](docs/building.md) guide. |
8 | | - |
9 | | -## Contributing to Keycloak |
10 | | - |
11 | | -Keycloak is an Open Source community-driven project and we welcome contributions as well as feedback from the community. We do have a few guidelines in place to help you be successful with your contribution to Keycloak. |
12 | | - |
13 | | -Firstly, if you want to contribute a larger change to Keycloak we ask that you open a |
14 | | -discussion first. For minor changes you can skip this part and go straight ahead to sending a contribution. Bear in mind that if you open a discussion first you can identify if the change will be accepted, as well as getting early feedback. |
15 | | - |
16 | | -Here's a quick checklist for a good PR, more details below: |
17 | | - |
18 | | -1. A discussion around the change (https://github.com/keycloak/keycloak/discussions/categories/ideas) |
19 | | -2. A GitHub Issue with a good description associated with the PR |
20 | | -3. One feature/change per PR |
21 | | -4. One commit per PR |
22 | | -5. PR rebased on main (`git rebase`, not `git pull`) |
23 | | -5. [Good descriptive commit message, with link to issue](#commit-messages-and-issue-linking) |
24 | | -6. No changes to code not directly related to your PR |
25 | | -7. Includes functional/integration test |
26 | | -8. Includes documentation |
27 | | - |
28 | | -Once you have submitted your PR please monitor it for comments/feedback. We reserve the right to close inactive PRs if |
29 | | -you do not respond within 2 weeks (bear in mind you can always open a new PR if it is closed due to inactivity). |
30 | | - |
31 | | -Also, please remember that we do receive a fairly large amount of PRs and also have code to write ourselves, so we may |
32 | | -not be able to respond to your PR immediately. The best place to ping us is on the thread you started on the dev mailing list. |
33 | | - |
34 | | -### Finding something to work on |
35 | | - |
36 | | -If you would like to contribute to Keycloak, but are not sure exactly what to work on, you can find a number of open |
37 | | -issues that are awaiting contributions in |
38 | | -[issues](https://github.com/keycloak/keycloak/issues). |
39 | | - |
40 | | -### Open a discussion on a proposed change |
41 | | - |
42 | | -As Keycloak is a community-driven project we require contributors to open a discussion on what they are planning to contribute. |
43 | | - |
44 | | -Discussions should first and foremost be done through [GitHub Discussions](https://github.com/keycloak/keycloak/discussions/categories/ideas). |
45 | | - |
46 | | -The [Keycloak Dev Mailing List](https://groups.google.com/forum/#!forum/keycloak-dev) can be used to notify the community on your new discussion, and can also be used for more low-level implementation discussions. |
47 | | - |
48 | | -For very large proposals it can be inefficient to capture all the information in the GitHub Discussion. In this cases a separate design proposal can be sent to the [Keycloak Community repository](https://github.com/keycloak/keycloak-community/tree/main/design), and linked to from the GitHub Discussion. |
49 | | - |
50 | | -### Create an issue |
51 | | - |
52 | | -Take your time to write a proper issue including a good summary and description. |
53 | | - |
54 | | -Remember this may be the first thing a reviewer of your PR will look at to get an idea of what you are proposing |
55 | | -and it will also be used by the community in the future to find about what new features and enhancements are included in |
56 | | -new releases. |
57 | | - |
58 | | -### Implementing |
59 | | - |
60 | | -Details for building from source and working with the codebase are provided in the |
61 | | -[building and working with the code base](docs/building.md) guide. |
62 | | - |
63 | | -Do not format or refactor code that is not directly related to your contribution. If you do this it will significantly |
64 | | -increase our effort in reviewing your PR. If you have a strong need to refactor code then submit a separate PR for the |
65 | | -refactoring. |
66 | | - |
67 | | -### Testing |
68 | | - |
69 | | -Details for implementing tests are provided in the [writing tests](docs/tests-development.md) guide. |
70 | | - |
71 | | -Do not add mock frameworks or other testing frameworks that are not already part of the testsuite. Please write tests |
72 | | -in the same way as we have written our tests. |
73 | | - |
74 | | -### Documentation |
| 6 | +Most of the contribution rules from the [main Keycloak repository](https://github.com/keycloak/keycloak/blob/main/CONTRIBUTING.md) applies to the |
| 7 | +Keycloak client libraries as well. Below some rules specific to client libraries. |
75 | 8 |
|
76 | | -We require contributions to include relevant documentation. Before submitting your code changes, please take the time to review the [documentation](docs/documentation/README.md) guide and ensure that any necessary documentation changes are included in your pull request. |
77 | | - |
78 | | -### Submitting your PR |
79 | | - |
80 | | -When preparing your PR make sure you have a single commit and your branch is rebased on the main branch from the |
81 | | -project repository. |
82 | | - |
83 | | -This means use the `git rebase` command and not `git pull` when integrating changes from main to your branch. See |
84 | | -[Git Documentation](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) for more details. |
85 | | - |
86 | | -We require that you squash to a single commit. You can do this with the `git rebase -i HEAD~X` command where X |
87 | | -is the number of commits you want to squash. See the [Git Documentation](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) |
88 | | -for more details. |
89 | | - |
90 | | -The above helps us review your PR and also makes it easier for us to maintain the repository. It is also required by |
91 | | -our automatic merging process. |
92 | | - |
93 | | -Please, also provide a good description [commit message, with a link to the issue](#commit-messages-and-issue-linking). |
94 | | -We also require that the commit message includes a link to the issue ([linking a pull request to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)). |
95 | | - |
96 | | -### Developer's Certificate of Origin |
97 | | - |
98 | | -Any contributions to Keycloak must only contain code that can legally be contributed to Keycloak, and which the Keycloak |
99 | | -project can distribute under its license. |
100 | | - |
101 | | -Prior to contributing to Keycloak please read the [Developer's Certificate of Origin](https://developercertificate.org/) |
102 | | -and sign-off all commits with the `--signoff` option provided by `git commit`. For example: |
103 | | - |
104 | | -``` |
105 | | -git commit --signoff --message "This is the commit message" |
106 | | -``` |
107 | | - |
108 | | -This option adds a `Signed-off-by` trailer at the end of the commit log message. |
109 | | - |
110 | | -### Commit messages and issue linking |
111 | | - |
112 | | -The format for a commit message should look like: |
113 | | - |
114 | | -``` |
115 | | -A brief descriptive summary |
116 | | -
|
117 | | -Optionally, more details around how it was implemented |
118 | | -
|
119 | | -Closes #1234 |
120 | | -``` |
121 | | - |
122 | | -The very last part of the commit message should be a link to the GitHub issue, when done correctly GitHub will automatically link the issue with the PR. There are 3 alternatives provided by GitHub here: |
123 | | - |
124 | | -* Closes: Issues in the same repository |
125 | | -* Fixes: Issues in a different repository (this shouldn't be used, as issues should be created in the correct repository instead) |
126 | | -* Resolves: When multiple issues are resolved (this should be avoided) |
127 | | - |
128 | | -Although, GitHub allows alternatives (close, closed, fix, fixed), please only use the above formats. |
129 | | - |
130 | | -Creating multi line commit messages with `git` can be done with: |
131 | | - |
132 | | -``` |
133 | | -git commit -m "Summary" -m "Optional description" -m "Closes #1234" |
134 | | -``` |
135 | | - |
136 | | -Alternatively, `shift + enter` can be used to add line breaks: |
137 | | - |
138 | | -``` |
139 | | -$ git commit -m "Summary |
140 | | -> |
141 | | -> Optional description |
142 | | -> |
143 | | -> Closes #1234" |
144 | | -``` |
145 | | - |
146 | | -For more information linking PRs to issues refer to the [GitHub Documentation](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). |
147 | | - |
148 | | -### Contributing Translations |
| 9 | +## Building and working with the codebase |
149 | 10 |
|
150 | | -In order to provide translations for Keycloak, kindly follow the instructions provided in [Translation Docs](./docs/translation.md). |
| 11 | +See [README](README.md) for some general rules with the details about client libraries codebase, documentation and the |
| 12 | +testsuite. |
| 13 | + |
| 14 | +## Syncing the files |
| 15 | + |
| 16 | +As pointed in the [README](README.md) some files are not "owned" by this repository, but are periodically synced from the |
| 17 | +Keycloak codebase main repository. So if you want to update any of these files, it needs to be updated first in the [main |
| 18 | +Keycloak codebase](https://github.com/keycloak/keycloak). So in general, the steps needed are usually: |
| 19 | + |
| 20 | +1) Possibly create the [issue in the keycloak-client](https://github.com/keycloak/keycloak-client/issues) with the |
| 21 | + description of the bug or RFE (This is not specific to syncing, but it |
| 22 | + usually always needed for any change anywhere in keycloak-client). This step can be omitted if you think that all the |
| 23 | + files, which need changing, are owned by keycloak repository. |
| 24 | +2) Create also [the issue in keycloak](https://github.com/keycloak/keycloak/issues) |
| 25 | +3) Send [PR to keycloak](https://github.com/keycloak/keycloak/pulls) with your changes in the client files. This may |
| 26 | + eventually require more changes in other files too (like for example adding the test in the main Keycloak repository etc) |
| 27 | +4) Once the PR is merged, it needs to be available under last release branch. For example https://github.com/keycloak/keycloak/tree/release/26.0 . So |
| 28 | + it is needed to either wait for Keycloak major or minor release (this happen once in 3-4 months. During the major/minor |
| 29 | + release, the new `release/XY` branch is created from the current `main` branch and this one then will be used as a base |
| 30 | + for syncing to keycloak-client) or make sure that your |
| 31 | + issue is backported to the last `release/XY` branch in the keycloak repository. |
| 32 | +5) Once the above is done, you can sync the sources to Keycloak-client and send the PR in keycloak-client. However this step is |
| 33 | + possibly not needed to be done as we have GH workflow, which periodically sync the sources from Keycloak and sends the pull request |
| 34 | + itself. |
0 commit comments