|
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 | 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. |
6 | 6 |
|
| 7 | +# Setting Up Your Development Environment |
| 8 | + |
| 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 | + |
| 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 | + |
7 | 95 | ### Git Flow |
8 | 96 |
|
9 | 97 | Fork the repo to your own github account. From there, you can add the ForgeRock repository as an upstream. |
10 | 98 |
|
11 | 99 | `git remote add upstream [email protected]:ForgeRock/forgerock-javascript-sdk.git` |
12 | 100 |
|
13 | | -## Here is a checklist of items to ensure your Pull Request is reviewed and ready to be merged: |
| 101 | +Please make PR's against the develop branch, which is the default branch. |
| 102 | + |
| 103 | +## Changesets |
| 104 | + |
| 105 | +We use changesets for releasing our packages. you can add a changeset when needed (when a change should require a release) using `pnpm changeset` |
| 106 | + |
| 107 | +fill out the TUI information and add this to your PR. |
| 108 | + |
| 109 | +More information can be found on the [changesets docs](https://changesets-docs.vercel.app/en) |
| 110 | + |
| 111 | +## Standards of Practice |
| 112 | + |
| 113 | +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. |
| 114 | + |
| 115 | +For more details on our Standards of Practice, please refer to the SDK Standards of Practice documentation. |
| 116 | + |
| 117 | +### Here is a checklist of items to ensure your Pull Request is reviewed and ready to be merged: |
14 | 118 |
|
15 | 119 | - [ ] Please make all pull requests against `develop` branch. |
16 | 120 | - [ ] Fill out the Pull Request template that appears when you open a PR. |
|
0 commit comments