|
1 | | -# Contributing to Forgerock's Javascript SDK |
| 1 | +# Contribution Guidelines for Ping SDK for Javascript |
2 | 2 |
|
3 | | -:+1::tada: First off, thanks for taking the time to contribute! :tada::+1: |
| 3 | +Welcome! We are excited that you are interested in contributing to the Ping SDK for JavaScript. This document will guide you through the steps required to contribute to the project. |
4 | 4 |
|
5 | | -The following is a set of guidelines for contributing to the Forgerock SDK and its packages, which are hosted in the [ForgeRock organization](https://github.com/forgerock) on GitHub. |
| 5 | +The following is a set of guidelines for contributing to the Ping SDK and its packages, which are hosted in the [ForgeRock organization](https://github.com/forgerock) on GitHub. |
6 | 6 |
|
7 | | -### Git Flow |
| 7 | +# Setting Up Your Development Environment |
8 | 8 |
|
9 | | -Fork the repo to your own github account. From there, you can add the ForgeRock repository as an upstream. |
| 9 | +Before you can contribute to the Ping SDK for Javascript, you'll need to set up your development environment. This section describes the prerequisites and steps needed to start using the project in your local machine. |
10 | 10 |
|
11 | | -`git remote add upstream [email protected]:ForgeRock/forgerock-javascript-sdk.git` |
| 11 | +## Prerequisites |
| 12 | + |
| 13 | +- GitHub account. |
| 14 | +- Git installed. |
| 15 | +- (pnpm)[https://pnpm.io/installation] |
| 16 | +- Node 20 |
| 17 | +- Setup an Advanced Identity Cloud tenant or PingAM instance, as described in the Documentation. |
| 18 | + |
| 19 | +## Fork and Clone the Repository |
| 20 | + |
| 21 | +Fork the repository to your own GitHub account by clicking the "Fork" button at the top-right of the repository page. |
| 22 | + |
| 23 | +Clone your forked repository to your local machine: |
| 24 | + |
| 25 | +git clone https://github.com/your-username/forgerock-javascript-sdk.git |
| 26 | + |
| 27 | +- Navigate into the project folder: |
| 28 | + |
| 29 | +- cd forgerock-javascript-sdk |
| 30 | + |
| 31 | +- Build the project to make sure it works, `pnpm build` |
| 32 | + |
| 33 | +### Commands in the repo |
| 34 | + |
| 35 | +Most commands live within the local `project.json` of the package you are working in. You can use the project.json and the Nx vscode extension to run commands via the code lens. |
| 36 | + |
| 37 | +Alternatively there are many ways to run commands, of which a few are to be listed below: |
| 38 | +`pnpm build` will run build on all projects |
| 39 | +`pnpm lint` will run lint on all projects |
| 40 | +`pnpm test` will run unit tests on all projects |
| 41 | +`pnpm e2e` will run e2e tests for all e2e apps |
| 42 | + |
| 43 | +You can run commands with `nx` like so: |
| 44 | +`pnpm nx build <name in project.json>` |
| 45 | + |
| 46 | +_examples_: |
| 47 | + |
| 48 | +``` |
| 49 | +`pnpm nx build javascript-sdk` |
| 50 | +`pnpm nx lint javascript-sdk` |
| 51 | +`pnpm nx test javascript-sdk` |
| 52 | +`pnpm nx e2e autoscript-suites` |
| 53 | +`pnpm nx serve autoscript-apps` |
| 54 | +``` |
| 55 | + |
| 56 | +## Understanding the Project Structure |
| 57 | + |
| 58 | +The Ping SDK for Javascript is organized in a modular way. This section is designed to help you understand the layout of the project. We will break down each of the folders and what modules you will find there. Getting familiar with the project structure will make contributing easier and more efficient. |
| 59 | + |
| 60 | +``` |
| 61 | + e2e/ |
| 62 | + autoscript-apps |
| 63 | + autoscript-suites |
| 64 | + mock-api |
| 65 | + mock-api-v2 |
| 66 | + token-vault-app |
| 67 | + token-vault-interceptor |
| 68 | + token-vault-proxy |
| 69 | + token-vault-suites |
| 70 | + packages/ |
| 71 | + javascript-sdk |
| 72 | + ping-protect |
| 73 | + token-vault |
| 74 | +
|
| 75 | +``` |
| 76 | + |
| 77 | +### Package overview |
| 78 | + |
| 79 | +- _javascript-sdk_: This is the core module that powers the rest of the packages. OIDC/AIC Callback support/etc |
| 80 | +- _ping-protect_: This is the core package that allows a developer to interact with the Ping Protect signals api. This module will load the signals sdk for you, and provides a lightweight interface for interacting with the modules. |
| 81 | +- _token-vault_: A propreitary way of managing tokens for environments which require high security. |
| 82 | + |
| 83 | +### E2E Overview |
| 84 | + |
| 85 | +``` |
| 86 | +- *autoscript-suites*: The e2e test location for writing modular and journey e2e's with the javascript-sdk or ping-protect. |
| 87 | +- *autoscript-apps*: A multi-page web application for loading javascript files which call through the journey you are testing programatically |
| 88 | +- *mock-api*: A backend server that serves mock data for the autoscript-apps. This is hard-coded data to mimic what the actual AIC Tenant will respond with |
| 89 | +- *mock-api-v2*: A new version of the mock api, development of this is moved over to the new Ping SDK repo. |
| 90 | +- *token-vault-app*: The application which sets up Token-Vault for testing |
| 91 | +- *token-vault-proxy*: The proxy application (required) for using token vault |
| 92 | +- *token-vault-suites*: The e2e test location for playwright tests. |
| 93 | +``` |
| 94 | + |
| 95 | +## Changesets |
| 96 | + |
| 97 | +We use changesets for releasing our packages. you can add a changeset when needed (when a change should require a release) using `pnpm changeset` |
| 98 | + |
| 99 | +fill out the TUI information and add this to your PR. |
| 100 | + |
| 101 | +More information can be found on the [changesets docs](https://changesets-docs.vercel.app/en) |
| 102 | + |
| 103 | +## Standards of Practice |
| 104 | + |
| 105 | +We ask that all contributors to this project adhere to our engineering Standard for team culture, practices and code of conduct. We expect everyone to be respectful, inclusive, and collaborative. Any violations will be handled according to the project's guidelines. |
| 106 | + |
| 107 | +For more details on our Standards of Practice, please refer to the [SDK Standards of Practice](https://github.com/ForgeRock/sdk-standards-of-practice) documentation. |
12 | 108 |
|
13 | 109 | ## Here is a checklist of items to ensure your Pull Request is reviewed and ready to be merged: |
14 | 110 |
|
| 111 | +This section covers how to create your changes, and submit them for review by Ping Identity engineers |
| 112 | +by using a Pull Request. A PR is a formal request to merge your changes from your forked repository into |
| 113 | +the main project. The following steps will guide you on creating a well-structured PR that |
| 114 | +facilitates efficient review and integration of your contributions. |
| 115 | + |
| 116 | +### Create a New Branch |
| 117 | + |
| 118 | +Always create a new branch to work on your changes. Avoid making changes directly on the `develop` or `master` branch. |
| 119 | + |
| 120 | +```bash |
| 121 | +git checkout -b feature/my-new-feature |
| 122 | +``` |
| 123 | + |
| 124 | +### Release affecting changes |
| 125 | + |
| 126 | +If the change you have made should be reflected in a release, be sure to add a changeset with `pnpm changeset` |
| 127 | + |
| 128 | +### Commit Your Changes |
| 129 | + |
| 130 | +Once you’ve made your changes, commit them with a clear and descriptive message. Note that our |
| 131 | +repository requires all commits to be signed. For more information on signing commits, please refer to |
| 132 | +the GitHub Docs |
| 133 | + |
| 134 | +The commit message should follow this structure: |
| 135 | + |
| 136 | +[Conventional Commit Conventions](https://www.conventionalcommits.org/en/v1.0.0-beta.4/#summary) |
| 137 | + |
| 138 | +``` |
| 139 | + [TYPE](scope?optional) Short description of the changes |
| 140 | + Types: |
| 141 | +
|
| 142 | + feat: A new feature |
| 143 | + fix: A bug fix |
| 144 | + docs: Documentation changes |
| 145 | + refactor: Code refactoring (no feature change) |
| 146 | + test: Adding or modifying tests |
| 147 | + chore: not a release affecting change. |
| 148 | + ci: ci related changes |
| 149 | +``` |
| 150 | + |
| 151 | +Example: |
| 152 | + |
| 153 | +``` |
| 154 | +git commit -S -m "feat: add login functionality" |
| 155 | +``` |
| 156 | + |
| 157 | +### Push Your Changes |
| 158 | + |
| 159 | +After committing your changes, push them to your fork: |
| 160 | + |
| 161 | +``` |
| 162 | +git push origin feature/my-new-feature |
| 163 | +``` |
| 164 | + |
| 165 | +### Create a Pull Request |
| 166 | + |
| 167 | +Go to your fork on GitHub. |
| 168 | + |
| 169 | +Click on the "New Pull Request" button. |
| 170 | + |
| 171 | +Select the base repository and base branch (usually develop), then select the branch you just pushed. |
| 172 | + |
| 173 | +### Fill out the PR Template |
| 174 | + |
| 175 | +Make sure to fill out the PR template provided. The template helps us better understand your change. Typically, a PR will require the following information: |
| 176 | + |
| 177 | +Add a title and description for the PR. The description should include: |
| 178 | + |
| 179 | +- What was changed and why. |
| 180 | +- Any related issues. |
| 181 | +- Any additional context if necessary, for example relevant screenshots or breaking changes. |
| 182 | +- Once everything looks good, submit the PR for review. |
| 183 | + |
| 184 | +### PR Review and Feedback |
| 185 | + |
| 186 | +Once the PR is submitted, the team will review it. Be prepared to: |
| 187 | + |
| 188 | +- Address any feedback or requested changes. |
| 189 | +- Keep your branch up to date with the base branch by rebasing or merging. |
| 190 | + |
| 191 | +### Definition of Done |
| 192 | + |
15 | 193 | - [ ] Please make all pull requests against `develop` branch. |
16 | 194 | - [ ] Fill out the Pull Request template that appears when you open a PR. |
17 | 195 | - [ ] Please ensure `pnpm run lint` reports no issues. |
|
0 commit comments