Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
210 lines (146 loc) · 8.97 KB

CONTRIBUTING.md

File metadata and controls

210 lines (146 loc) · 8.97 KB

How to Contribute

If you find something interesting you want contribute to the repo, feel free to raise a PR, or open an issue for features you'd like to see added.

For first time contributors

Proposing a Change

For small bug-fixes, documentation updates, or other trivial changes, feel free to jump straight to submitting a pull request.

If the changes are larger (API design, architecture, etc), opening an issue can be helpful to reduce implementation churn as we hash out the design.

Requirements

Important

The owners of this repo develop on MacOS with Apple Silicon chips. All recommendations are based on that build environment.

Since this repo uses Bazel to build cross-platform, it requires tools that you may not use directly. Please set-up all required tools.

Tool Version Recommendations
MacOS Tahoe (26) Update via System Settings. Bazel / Xcode / MacOS are extremely sensitive to each other. This is the version we develop with and know to work. Using versions beyond this might break.
bazelisk Latest Install through homebrew
pnpm >= 9.0.0 Install via volta. Our repo specifies an appropriate pnpm version in our package.json for Volta.
Swift >= 5.5 This comes installed with Xcode. Do not install separately.
Xcode 26.4 Download from Apple. Having this exact Xcode version is extremely important. Bazel / Xcode / MacOS are extremely sensitive to each other. This is the version we develop with and know to work. Using versions beyond this might break.
Python >= 2.7.18 Use pyenv to manage versions
Signed Commits - For your convenience, set git to sign all commits by default as described here

Building and Testing Locally (All platforms)

This project also contains just recipes for many common commands. They can be listed using just -l

Player

For speed and consistency, this repo leverages bazel as its main build tool. Check out the bazel docs for more info.

After forking the repo, run builds using bazel to test, build and run:

Docs Sites

The docs site can be run locally using:

bazel run //docs/site:dev

which will run an instance on http://localhost:4321.

Documentation Previews

To trigger a docs preview, collaborators can add a /docs comment to any PR. This will build and deploy a docs preview to the Player Docs Repo in the pr/{PR_NUMBER} folder structure. A comment will be added to the PR with the preview link.

The docs preview will be available at: https://player-ui.github.io/pr/{PR_NUMBER}/

Canary Releases

When a collaborator comments /canary on a PR, it will trigger a canary release that publishes NPM packages with a canary version. A comment will be added to the PR with the version information.

Production Documentation

When a PR is merged, any docs/site changes will be deployed to the next folder in https://github.com/player-ui/player-ui.github.io, which stores the built files for the site.

The OSS site is deployed with the following route logic:

  • The next route correlates to the doc site generated by the latest build of Player. Every PR merged into the main branch (unless opted out) will generate a next build so that functionality can be immediately consumed.
  • The latest route correlates to the doc site generated from the last non-next release of Player. These are releases that are we intentionally choose to cut and have a non-tagged semvar version.
  • The 0 route contains the docs for the last 0.x.x release. For every major release, we preserve the doc site for the last version released for it to allow folks who can't upgrade immediately to still have access to docs that are relevant for them.

For Android

If you are interested in contributing for android, follow our android guide

For iOS

Once you have done the set-up below, please refer to our iOS Dev Wiki page for more advanced iOS development info.

Additional Set-up

iOS Development requires a bit more set-up.

  1. In the terminal, run which brew. You should have /opt/homebrew/bin/brew.

    • If you instead have /usr/local or something similar, you have the Intel chip homebrew. You need Apple Silicon homebrew. This will let you run the project without Rosetta. Follow the next step.

  2. If you need to replace Intel homebrew, do the following. Keep in mind that this will remove everything you have installed through homebrew. E.g. existing installations of VSCode, xcodes, rsync, etc.

    1. Delete all your formulas and casks. This is to ensure no conflicts with the new homebrew. If you don’t feel comfortable deleting everything, delete at least bazelisk.

      brew remove --force $(brew list --formula)```
brew remove --cask --force $(brew list)

    2. Delete homebrew

      /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"

    3. Install homebrew again. Make sure to follow the steps to add homebrew to your PATH.

    4. Run which brew and make sure you now have /opt/homebrew/bin/brew

  3. (Optional) We recommend using xcodes via homebrew to manage multiple Xcode versions. If you have multiple Xcode versions, select the needed version of Xcode:

    xcodes select {version}

    E.g.

    xcodes select 26.4

  4. brew install rsync. This fixes a bunch of permission denied issues.

    1. Close and re-open the terminal.
    2. Run which rsync to make sure you’re using the homebrew one. If it’s not the homebrew rsync, something is wrong and needs to be fixed.

To Run

  1. Generate the .xcodeproj to open and work in Xcode.

    bazel run //ios:xcodeproj

  2. Open the .xcodeproj. If Xcode is your default app for xcodeprojs, you can use this:

    open ios/PlayerUI.xcodeproj/

    [!IMPORTANT] You may need to regenerate the project when adding new files or modifying targets. Close Xcode first, then regenerate and re-open.

  3. In Xcode, switch to the PlayerUIDemo target. Run the app.

  4. To run the tests, switch to the Test Navigator. You can run any suite directly from Xcode. The Test Navigator may show 0 tests in each suite until you actually run the suite.

Bazel

The demo app can also be built and launched in a simulator from the command line with bazel:

bazel run //ios/demo:PlayerUIDemo

Submitting a Pull Request

Prior to submitting a pull request, ensure that your fork and branch are up to date with the lastest changes on main.

Any new features should have corresponding tests that exercise all code paths, and public symbols should have docstrings at a minimum. For more complex features, adding new documentation pages to the site to help guide users to consume the feature would be preferred.

When you're ready, submit a new pull request to the main branch and the team will be notified of the new requested changes. We'll do our best to respond as soon as we can.

Releases

When a PR is merged, it will generate a next release, so something like 0.12.0-next.0 which can then be used in your project. This is done so that you can consume the latest changes without having to wait for a release to be cut.

Canary Releases

To trigger a canary release, collaborators can add a /canary comment to any PR. Note: Canary builds can only be requested by collaborators.

Inspired by react's How to Contribute