Skip to content

chore: contributing-information #543

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

chore: contributing-information #543

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 107 additions & 3 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,120 @@
# Contributing to Forgerock's Javascript SDK
# Contribution Guidelines for Ping SDK for Javascript

:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
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.

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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
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.

# Setting Up Your Development Environment

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.

## Prerequisites

- GitHub account.
- Git installed.
- (pnpm)[https://pnpm.io/installation]
- Node 20
- Setup an Advanced Identity Cloud tenant or PingAM instance, as described in the Documentation.

## Fork and Clone the Repository

Fork the repository to your own GitHub account by clicking the "Fork" button at the top-right of the repository page.

Clone your forked repository to your local machine:

git clone https://github.com/your-username/forgerock-javascript-sdk.git

- Navigate into the project folder:

- cd forgerock-javascript-sdk

- Build the project to make sure it works, `pnpm build`

### Commands in the repo

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.

Alternatively there are many ways to run commands, of which a few are to be listed below:
`pnpm build` will run build on all projects
`pnpm lint` will run lint on all projects
`pnpm test` will run unit tests on all projects
`pnpm e2e` will run e2e tests for all e2e apps

You can run commands with `nx` like so:
`pnpm nx build <name in project.json>`

_examples_:

```
`pnpm nx build javascript-sdk`
`pnpm nx lint javascript-sdk`
`pnpm nx test javascript-sdk`
`pnpm nx e2e autoscript-suites`
`pnpm nx serve autoscript-apps`
```

## Understanding the Project Structure

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.

```
e2e/
autoscript-apps
autoscript-suites
mock-api
mock-api-v2
token-vault-app
token-vault-interceptor
token-vault-proxy
token-vault-suites
packages/
javascript-sdk
ping-protect
token-vault

```

### Package overview

- _javascript-sdk_: This is the core module that powers the rest of the packages. OIDC/AIC Callback support/etc
- _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.
- _token-vault_: A propreitary way of managing tokens for environments which require high security.

### E2E Overview

```
- *autoscript-suites*: The e2e test location for writing modular and journey e2e's with the javascript-sdk or ping-protect.
- *autoscript-apps*: A multi-page web application for loading javascript files which call through the journey you are testing programatically
- *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
- *mock-api-v2*: A new version of the mock api, development of this is moved over to the new Ping SDK repo.
- *token-vault-app*: The application which sets up Token-Vault for testing
- *token-vault-proxy*: The proxy application (required) for using token vault
- *token-vault-suites*: The e2e test location for playwright tests.
```

### Git Flow

Fork the repo to your own github account. From there, you can add the ForgeRock repository as an upstream.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can move this content to the section Fork and Clone the Repository above

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we still need to address it

`git remote add upstream [email protected]:ForgeRock/forgerock-javascript-sdk.git`

## Here is a checklist of items to ensure your Pull Request is reviewed and ready to be merged:
Please make PR's against the develop branch, which is the default branch.

## Changesets

We use changesets for releasing our packages. you can add a changeset when needed (when a change should require a release) using `pnpm changeset`

fill out the TUI information and add this to your PR.

More information can be found on the [changesets docs](https://changesets-docs.vercel.app/en)

## Standards of Practice

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we provide a link to these standards/guidelines?

For more details on our Standards of Practice, please refer to the SDK Standards of Practice documentation.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For more details on our Standards of Practice, please refer to the SDK Standards of Practice documentation.
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.

### Here is a checklist of items to ensure your Pull Request is reviewed and ready to be merged:

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Here is a checklist of items to ensure your Pull Request is reviewed and ready to be merged:
## Creating a Pull Request (PR)
This section covers how to create your changes, and submit them for review by Ping Identity engineers
by using a Pull Request. A PR is a formal request to merge your changes from your forked repository into
the main project. The following steps will guide you on creating a well-structured PR that
facilitates efficient review and integration of your contributions.
### Create a New Branch
Always create a new branch to work on your changes. Avoid making changes directly on the `develop` or `master` branch.
```bash
git checkout -b feature/my-new-feature

Make Your Changes

Implement the required changes or new features. Make sure to write clean, well-commented, and readable code. If applicable, include tests and documentation for the new functionality.

Commit Your Changes

Once you’ve made your changes, commit them with a clear and descriptive message. Note that our
repository requires all commits to be signed. For more information on signing commits, please refer to
the GitHub Docs

The commit message should follow this structure:

[TYPE] Short description of the changes

Types:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation changes
  • refactor: Code refactoring (no feature change)
  • test: Adding or modifying tests

Example:

git commit -S -m "feat: add login functionality"

Push Your Changes

After committing your changes, push them to your fork:

 git push origin feature/my-new-feature

Create a Pull Request

  1. Go to your fork on GitHub.

  2. Click on the "New Pull Request" button.

  3. Select the base repository and base branch (usually develop), then select the branch you just pushed.

  4. Fill out the PR Template

    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:

    • Add a title and description for the PR. The description should include:
      • What was changed and why.
      • Any related issues.
      • Any additional context if necessary, for example relevant screenshots or breaking changes.

    Once everything looks good, submit the PR for review.

PR Review and Feedback

Once the PR is submitted, the team will review it. Be prepared to:

  • Address any feedback or requested changes.
  • Keep your branch up to date with the base branch by rebasing or merging.

Here is a checklist of items to ensure your Pull Request is reviewed and ready to be merged:

- [ ] Please make all pull requests against `develop` branch.
- [ ] Fill out the Pull Request template that appears when you open a PR.
Expand Down
20 changes: 13 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@ The Ping SDK for JavaScript enables you to quickly integrate Ping products into

Use the SDKs to leverage _[Intelligent Access](https://www.pingidentity.com/en/platform/capabilities/intelligent-access.html)_ to easily step through each stage of an authentication tree by using callbacks.

<!------------------------------------------------------------------------------------------------------------------------------------>
<!------------------------------------------------------------------------------------------------------------------------------------>

<!-- REQUIREMENTS - Supported AM versions, API versions, any other requirements. -->

## Requirements
Expand All @@ -38,9 +39,11 @@ Use the SDKs to leverage _[Intelligent Access](https://www.pingidentity.com/en/p
- Edge 44 (Legacy): requires one polyfill for TextEncoder, [`fast-text-encoding` is recommended](https://www.npmjs.com/package/fast-text-encoding)

- npm

- npm 7+ is required to use this project and the sample apps, since npm workspaces are used to install dependencies in sub-projects such as the sample apps

<!------------------------------------------------------------------------------------------------------------------------------------>

<!-- INSTALLATION -->

## Installation
Expand All @@ -49,6 +52,10 @@ Use the SDKs to leverage _[Intelligent Access](https://www.pingidentity.com/en/p
npm install @forgerock/javascript-sdk
```

## Contributing

Please see the [Contributing](./CONTRIBUTING.md) file linked here.

## Samples

ForgeRock provides these samples to help demonstrate SDK functionality/implementation. They are provided "as is" and are not official products of Ping Identity Corporation and are not officially supported.
Expand All @@ -64,6 +71,7 @@ To try out the Ping SDK for JavaScript please look at one of our samples:
- [**Angular Todo - `samples/angular-todo`**](https://github.com/ForgeRock/sdk-sample-apps/blob/main/angular-todo/README.md)

<!------------------------------------------------------------------------------------------------------------------------------------>

<!-- DOCS - Link off to the AM-centric documentation at sdks.forgerock.com. -->

## Documentation
Expand All @@ -75,6 +83,7 @@ Documentation for the SDKs is provided at **<https://docs.pingidentity.com/sdks>
- API Reference documentation

<!------------------------------------------------------------------------------------------------------------------------------------>

<!-- SUPPORT -->

## Support
Expand All @@ -95,13 +104,9 @@ The support portal shows all currently open support tickets and allows you to ra
[Our version history can be viewed by visiting our CHANGELOG.md](https://github.com/ForgeRock/forgerock-javascript-sdk/blob/master/CHANGELOG.md).

<!------------------------------------------------------------------------------------------------------------------------------------>
<!-- COLLABORATION -->

## Contributing

If you would like to contribute to this project you can fork the repository, clone it to your machine and get started.

<!------------------------------------------------------------------------------------------------------------------------------------>

<!-- LEGAL -->

## Disclaimer
Expand All @@ -112,6 +117,7 @@ If you would like to contribute to this project you can fork the repository, clo
> Any action or suit relating to the use of the code may be brought only in the courts of a jurisdiction wherein Ping Identity Corporation resides or in which Ping Identity Corporation conducts its primary business, and under the laws of that jurisdiction excluding its conflict-of-law provisions.**

<!------------------------------------------------------------------------------------------------------------------------------------>

<!-- LICENSE - Links to the MIT LICENSE file in each repo. -->

## License
Expand All @@ -120,4 +126,4 @@ This project is licensed under the MIT License - see the [LICENSE](./packages/ja

---

&copy; Copyright 2020-2025 Ping Identity. All Rights Reserved
© Copyright 2020-2025 Ping Identity. All Rights Reserved
Loading