- Development Setup
- Coding Rules
- Commit Message Guidelines
- Connecting to the Qri backend
- Running Storybook
- Advanced: Managing Different Qri Repos
This document describes how to set up your development environment to build and test Qri, and
explains the basic mechanics of using git
and yarn
.
Before you can build Qri Desktop, you must install and configure the following dependencies on your machine:
-
Git: The Github Guide to Installing Git is a good source of information.
-
- If you don't have node installed, we recommend using homebrew to manage your package of node.
# Install Homebrew by running this script and following the prompts (pulled straight from the homebrew homepage) /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" # install node brew install node
-
Yarn: We use Yarn to install our dependencies (rather than using npm). See the detailed installation instructions.
-
Qri backend: The core functionality for working with Qri.
-
temp_registry_server: This is a package we developed for use in Desktop end-to-end (e2e) testing. For more info about running the tests, see the project README
To contribute code to Qri, you must have a GitHub account so you can push code to your own fork of Qri and open Pull Requests in the GitHub Repository.
First, create a Github account. Afterwards, go ahead and fork the Qri desktop repository (Learn more about forking).
To build Qri, you clone the source code repository and use Yarn to run the electron app:
# Clone your Github repository:
git clone https://github.com/qri-io/desktop.git
# Go to the Qri directory:
cd desktop
# Add the main Qri repository as an upstream remote to your repository:
git remote add upstream "https://github.com/qri-io/desktop.git"
# Install dependencies:
yarn
# open a new window to your terminal, and connect the qri backend to the network:
$ qri connect
# Run Qri in the developer environment:
yarn dev
# Use eslint to lint the files:
yarn lint
# Create a packaged version of Qri:
yarn build && yarn start
The yarn dev
command will launch a development version of the Qri electron app.
To get access to Chrome Developer Tools, use the keyboard shortcut Command-Shift-C.
This will only work if you are internal to Qri and have the correct keys
- change the frontend and backend version numbers in:
/package.json
/app/package.json
version.js
- run
make update-changelog
to update the changelog - write release notes
- build the correct version of the qri backend binary
- ensure it is executable (chmod +x qri)
- move the executable binary to the
/backend
directory - run
yarn dist
- ensure the Qri Desktop app running correctly and has all the correct version numbers
- submit a pr, once approved merge
- run
yarn dist --publish always
to create a release - Because notarizing the mac.zip file is broken in electron-builder right now (as per https://snippets.cacher.io/snippet/354a3eb7b0dcbe711383 & electron-userland/electron-builder#4299):
- compress the app file that exists in
/release/mac
- rename it to match the current mac.zip file in the
/release
directory - replace the old zip file with the new one
- run
./node_modules/app-builder-bin/mac/app-builder blockmap -i release/FILENAME.zip -o release/throwaway.zip
- app-builder is modifying the contents of the zip, which is messing up the notarization. The -o flag indicates an output file that app-builder can futz with without ruining the integrity of the original app
- take the updated file into from size, sha512 and blockMapSize
- update the
/release/latest-mac.yml
with that info - replace
FILENAME.zip
to the release page
To ensure consistency throughout the source code, keep these rules in mind as you are working:
- We use eslint coding style, please use standard to lint any changes before committing:
# Use eslint to lint files
yarn lint
The output will point you to which files/lines need to be changed in order to meet the standardJS formatting.
We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history. But also, we use the git commit messages to generate the Qri change log.
Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
The header is mandatory and the scope of the header is optional.
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.
If the commit reverts a previous commit, it should begin with revert:
, followed by the header
of the reverted commit.
In the body it should say: This reverts commit <hash>.
, where the hash is the SHA of the commit
being reverted.
A commit with this format is automatically created by the git revert
command.
Must be one of the following:
- feat: A new feature
- fix: A bug fix
- 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
- test: Adding missing or correcting existing tests
- chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
The scope could be anything specifying place of the commit change. For example NEED TO MAKE DECISION ABOUT THIS , etc...
You can use *
when the change affects more than a single scope.
The subject contains succinct description of the change:
- use the imperative, present tense: "change" not "changed" nor "changes"
- don't capitalize first letter
- no dot (.) at the end
Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.
The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit closes.
Breaking Changes should start with the word BREAKING CHANGE:
with a space or two newlines.
The rest of the commit message is then used for this.
A detailed explanation can be found in this document.
This documentation has been adapted from the Data Together, Hyper, and AngularJS documentation.
This Qri Desktop application is a Graphical User Interface (GUI) client of our Qri backend. The backend provides an API that this Desktop app utilizes to give our users all the great features Qri has to offer like creating datasets, viewing dataset commit history and pushing datasets to Qri cloud!
As such, developing on this Qri Desktop project relies on a connection to the Qri backend. To install the Qri backend on your machine, follow the instructions of your choice here and ensure that wherever the qri binary was installed has been added to your PATH. This will allow you to type qri
command line commands (e.g. qri connect
) at your terminal.
When this Qri Desktop app is running, it will look for the Qri backend in a few places in this order:
- Is there a qri node already running on your machine? This would happen if you've run
qri connect
in a different terminal window. If so, Qri Desktop will use this existing node. - Is there a qri binary already installed on your PATH? If yes, use that binary to spin up a qri node.
- Is there qri binary internal to this Desktop app (at
/desktop/backend/qri
)? If so, use that. This Desktop app comes packaged with qri binary when a user downloads the app and will look here as a last resort. For most Desktop users this is the only version of the Qri backend they may have. If you as a developer have forked this project and not downloaded the app, you will not have this internal binary and need to download it separately.
When developing new components for Qri Desktop, our team first builds them in Storybook. Storybook is a tool which allows us to build and showcase components in an isolated environment from our app.
To run Storybook to view our component library, simply run the yarn storybook
command in your terminal and you will be re-directed to your browser to view the stories. If you would only like to build the Storybook assets but not launch Storybook to open in-browser, you can run the yarn build-storybook
command.
When rendering Storybook stories which rely on fetched information from our qri
backend, you'll need to whitelist the Storybook domain to comply with our CORS policy. To do this, follow these steps:
- Set 'http://localhost:6006' as an entry under
allowedorigins
in theconfig.yaml
file of your local qri repo. (Note: your local qri repo is not a refence toqri
backend code. It is rather where your qri configuration, peer information, datasets, and other metadata are stored at yourQRI_PATH
.) You can make this change by either using theqri
command line and runningqri config set
or by directly editing theconfig.yaml
located at yourQRI_PATH
. - Ensure the
qri
backend is running to receive your request by runningqri connect
in your terminal.
Note: the knowledge and management of different local qri repos is not necessary for developing on Qri Desktop. It is useful however for testing and development purposes to have one or more repos outside of your default qri repo; you can play around with these and delete them easily if something breaks without worrying about the consequences. It is also useful to have a test repo set up when developing on a version of the Qri backend that requires a migration and would otherwise alter the configuration of your default qri repo.
A qri repo is a storage location where Qri stores its local information (e.g. configuration, peer information, IPFS data, Logbooks, etc). This term is not to be confused with the location of the Qri backend source code that you may have downloaded on your machine.
A qri repo is configured for a Qri user when they set up a qri instance. This can happen in one of two ways:
- When a CLI user runs
qri setup
at the command line after having installed the qri binary - When a user opens the Desktop app for the first time
Qri uses your os home directory (~/.qri
on macOS and Linux, or HOME\.qri
on Windows) to store your qri repo unless you override the default by setting the QRI_PATH
env var.
Let's imagine that we're working on a Desktop feature which relies on a dev version of the Qri backend that requires a migration. Instead of migrating our current default qri repo, we want to make a test one for this purpose. We need to build the Qri backend binary of the dev version and point to a new qri repo that we create.
- Build the binary: clone the version of the Qri backend that you'd like locally to a destination of your choice (e.g.
~/qri-dev
). Thencd
into theqri
directory and build this from source by runninggo build
. Runninggo build
creates a version of qri binary in the same directory in which you ran the command, meaning this binary will be separate from the default one on your PATH and will only be referenced when you directly call it. We just need to make sure we make this binary executable before running it. Do this by runningchmod +x qri
and then you'll be able run it (./qri
). - Set QRI_PATH: set the
QRI_PATH
env var to a location you create (e.g.export QRI_PATH=~/qri-dev/test-repo/qri
). - Set up new Qri instance: now that
QRI_PATH
is pointed to your new location,cd
into the folder where your localqri
binary resides (~/qri-dev/qri
in our example) and use your new localqri
executable to set up a new qri instance (./qri setup
). Note: if you were just creating a new qri instance without using a different version of the Qri backend, you could simply runqri setup
using the default qri binary on your PATH. - Spin up a new Qri node: run
./qri connect
in your terminal to spin up a qri node using this new Qri backend. - Start up the Desktop app: start up Desktop in a different terminal window (
yarn dev
).
To switch back to the default qri backend, kill the currently running node (killall -v qri
). To switch back to the default qri repo, delete QRI_PATH
(unset QRI_PATH
). It's recommended that you use the default qri backend when interacting with your default qri repo.