Skip to content

Latest commit

 

History

History
110 lines (75 loc) · 6.79 KB

CONTRIBUTING.md

File metadata and controls

110 lines (75 loc) · 6.79 KB
Raw

First, thank you for contributing to DIM! We're a community-driven project and we appreciate improvements, large and small.

Here are some tips to make sure your Pull Request (PR) can be merged smoothly:

  1. If you want to add a feature or make some change to DIM, consider filing an issue describing your idea first. This will give the DIM community a chance to discuss the idea, offer suggestions and pointers, and make sure what you're thinking of fits with the style and direction of DIM. If you want a more free-form chat, join our Discord.
  2. Resist the temptation to change more than one thing in your PR. Keeping PRs focused on a single change makes them much easier to review and accept. If you want to change multiple things, or clean up/refactor the code, make a new branch and submit those changes as a separate PR.
  3. All of our code is written in TypeScript and uses React to build UI components.
  4. Be sure to run pnpm fix before submitting your PR - it'll catch most style problems and make things much easier to merge.
  5. Don't forget to add a description of your change to docs/CHANGELOG.md so it'll be included in the release notes!

Developer Quick start

  1. Install Pre-requisites
  2. Clone
  3. Start Dev Server
  4. Get your own API key
  5. Enter API credentials

Pre-requisites

Note: It's often easier to use a package manager like Homebrew for Mac, or Chocolatey for Windows, and install the prerequisites through them.

  • Homebrew: brew install git nodejs corepack visual-studio-code
  • Chocolatey: choco install git nodejs-lts corepack vscode

Manual Install

  • Install Git
  • Install NodeJS
  • It is highly recommended to use VSCode to work on DIM. When you open DIM in VSCode, accept the recommended plugins it suggests (find them manually by searching "@recommended" in the Extensions window).
  • On Windows, restart your system after installing everything.

Enable Corepack

Corepack manages the version of pnpm, the package manager used by DIM. It comes with NodeJS and will automatically get the right version of pnpm for you.

Clone the repo

To locally run a copy of DIM, you can simply clone the code repository:

git clone https://github.com/DestinyItemManager/DIM.git

To contribute changes to the project, you'll want to:

  1. Make an account on GitHub
  2. Create an SSH key and add it to your account
  3. Fork DIM to make your own copy of the repository
  4. Clone the forked repository to your local machine
  5. Edit the local files
  6. Commit and push your code changes to your fork
  7. Create a Pull Request from your forked repository to the original upstream repository, allowing DIM maintainers to accept and merge your changes

More detailed information on these steps is here.

Start Dev Server

Once you have cloned the repository or a fork of the repository to your local machine, in the root directory:

  • Run pnpm install
    • If pnpm isn't installed, run corepack enable and try again, or install it manually.
      • If corepack enable fails, try running it with Administrator privileges.
      • If you're using PowerShell on Windows, you may need to run Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted to allow pnpm to run.
    • Linux-based developers will need to install build-essential (sudo apt-get install -y build-essential) prior to running pnpm install.
  • Run pnpm start

On Windows machines, this will also install SnoreToast to provide notifications for parts of the development process, like when a build completes.

Get your own API key:

  1. Go to Bungie's Developer Portal (you will have to be signed in)
  2. Click Create New App
  3. Enter any application name
  4. Enter https://github.com/YourGithubUsername/DIM under website
  5. For Oauth Client type, select Confidential
  6. Set your redirect url to https://localhost:8080/return.html (or whatever the IP or hostname is of your dev server)
  7. Select all scopes except the Administrate Groups/Clans
  8. Enter https://localhost:8080 as the Origin Header
  9. Check the box to agree to the Terms of Use and click Create New App

Enter API Credentials

This step will need to be done each time you clear your browser cache. You will be automatically redirected to a screen to enter these credentials if the app can't load them from local storage when it starts.

  1. Open your browser and navigate to https://localhost:8080 (your browser will likely give a security warning, it is safe to continue anyways, see Overview below for details)
  2. Copy your API-key, Oauth Client_id, and OAuth client_secret from bungie.net into DIM developer settings panel when it is loaded
  3. Below the section for Bungie API credentials, follow the instructions to generate a DIM API key

Development

Overview

The pnpm start step will create a hot-loading web server and a TLS cert/key pair. You will access your local development site by visiting https://localhost:8080. You will likely get a security warning about the certificate not being trusted. This is because it's a self-signed cert generated dynamically for your environment and is not signed by a recognized authority. Dismiss/advance past this warning to view your local DIM application.

Check code Style

  • pnpm fix will tell you if you're following the DIM code style (and automatically fix what it can). Check out the docs folder for more tips.

Translation

  • We use i18next for all our translated strings, so if you want to translate something that's currently English-only, take a look at that. Usually it's as simple as replacing some text with <span>{t('KEY')}</span> and then defining KEY in the config\i18n.json file.

  • pnpm i18n will add, sort, and prune src/locale/en.json. You should never manually edit src/locale/en.json. Some keys are obfuscated by code and will need to be added as comments into the code such as // t('LoadoutBuilder.ObfuscatedKey1'). If you have any questions, ping @delphiactual via GitHub, Slack, or Discord.