This guide will walk you through setting up your local computer to be able to compile and package Polar from the source code. Towards the end, there are steps to follow if you wish to open a PR to fix a bug or add a new feature. You will also find some productivity tips to improve the developer experience when making changes to the code.
Polar is a desktop application with its code written with web technologies (HTML5, CSS3, Javascript) at the lowest level. At a higher level, we use Typescript, ReactJS, Redux via easy-peasy, and CSS-in-JS via Emotion. The web app is hosted in a desktop shell powered by the Electron cross-platform application framework.
There is some software that is required to compile and run Polar locally. You'll need to visit the websites to find installation instructions for your operating system.
- git: version control system needed to download the source code
- NodeJS: cross-platform javascript runtime
- Yarn: package manager for Node dependencies
- Docker and Docker Compose: OS virtualization platform
- Mac and Windows: you can just install Docker Desktop
- Linux: you need to install Docker Server and Docker Compose separately
Once you have all of the required software installed, you can proceed to setup your local environment
These steps only need to be performed one time on your machine
Clone the git repo
$ git clone https://github.com/jamaljsr/polar.git
$ cd polar
Install package dependencies
$ yarn
When you run Polar in development mode, you will have access to the Chrome DevTools. This allows you to see the console logs, React components, Redux actions & state.
$ yarn dev
Note: press CTRL+C in the terminal to kill the app
To run Polar in production mode, you will need to create a distributable binary. This will create an executable file in the dist/
dir. You can copy it to your desktop and simply double-click on it whenever you want to launch the app.
$ yarn package
Note: It will only create an executable for the current operating system. So if you are running this on a Mac, it will create a Mac compatible binary.
If some time has passed since you cloned the Github repo and there are updates pushed to GitHub, you should pull those changes into your local copy of the source code. You must also update any new dependencies. After pulling the latest updates, you can use the commands above to run in dev mode or package a new binary to use.
$ git pull
$ yarn
So you'd like to contribute some help to make Polar better, here's how...
To modify the source code, you'll need a good code editor. Visual Studio Code is a great cross-platform editor that has a lot of plugins and built-in tooling to make writing code much more productive. Here are some VS Code extensions that are useful to work on Polar:
- Prettier - Code formatter
- ESLint
- TSLint
- TypeScript Import Sorter
- Code Spell Checker
- Jest Snippets
- GitLens
If you would like to fix a bug or implement a new feature, here are the recommended steps you should follow to open a PR to the Polar repo:
- On GitHub, create your own fork of the polar repo (docs)
- Clone your repo locally on your computer
$ git clone <your-repo-url>
- Create a branch for your changes. It it better to work out of a branch other than master if you are going to have multiple PR's open at the same time
$ git checkout -b fix-typo
- Run Polar in development mode
$ yarn dev
- Make the changes to the source code. Most changes will automatically update in the app via React/Redux hot-reload.
- Before committing your changes, be sure to lint your code
$ yarn lint:all
- Also run the unit tests to make sure they all pass and test coverage is satisfactory
$ yarn test:ci
- When you are ready to commit your changes to git, use a commit message that follows the Conventional Commits Specifications. You can do this in one of two ways:
- Manually
$ git add . $ git commit -m "fix(home): fixed typo on the home screen"
- With Guidance. You will be prompted to answer some questions which will generate a valid commit message
$ yarn cm ? Select the type of change that you are committing: (Use arrow keys) feat: A new feature fix: A bug fix improvement: An improvement to a current feature docs: Documentation only changes style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) refactor: A code change that neither fixes a bug nor adds a feature perf: A code change that improves performance refactor: A code change that neither fixes a bug nor adds a feature perf: A code change that improves performance test: Adding missing tests or correcting existing tests build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) chore: Other changes that do not modify src or test files revert: Reverts a previous commit ? What is the scope of this change (e.g. component or file name): (press enter to skip) home ? Write a short, imperative tense description of the change (max 61 chars): fixed typo on home screen ? Provide a longer description of the change: (press enter to skip) ? Are there any breaking changes? No ? Does this change affect any open issues? No
- Manually
- Push your changes back to your forked repo
$ git push
- Open a pull request on GitHub (docs)