From 7e7ff89e795094c641e6b369f77357254db6d1a4 Mon Sep 17 00:00:00 2001 From: Pavel Laptev Date: Mon, 11 Mar 2024 22:35:51 +0100 Subject: [PATCH] development.md updated - added Table of Content for east navigation - added Design section - fixed headings level. h1 could be only one a page - added dividers between sections --- DEVELOPMENT.md | 112 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 83 insertions(+), 29 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 8f9d1cebb..2a15dfc62 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -3,7 +3,36 @@ Alrighty, you want to get compiling. We love you already. Your parents raised you right. Let's get started. -# Overview +--- + +## Table of Contents + +- [Overview](#overview) +- [The Basics](#the-basics) + - [Prerequisites](#prerequisites) + - [Install dependencies](#install-dependencies) + - [Run the app](#run-the-app) + - [Lint & format](#lint--format) +- [Debugging](#debugging) + - [Logs](#logs) + - [Tokio](#tokio) +- [Building](#building) + - [Building on Windows](#building-on-windows) + - [File permissions](#file-permissions) + - [Perl](#perl) +- [Design](#design) +- [Contributing](#contributing) +- [Some Other Random Notes](#some-other-random-notes) + - [Icon generation](#icon-generation) + - [Release](#release) + - [Versioning](#versioning) + - [Publishing](#publishing) +- [Development mode OAuth login](#development-mode-oauth-login) + + +--- + +## Overview So how does this whole thing work? @@ -16,11 +45,13 @@ So everything that hits disk is in Rust, everything that the user sees is in HTML/JS. Specifically we use [Svelte](https://svelte.dev/) in Typescript for that layer. -# The Basics +--- + +## The Basics OK, let's get it running. -## Prerequisites +### Prerequisites First of all, this is a Tauri app, which is a Rust app. So go install Rust. The Tauri site has a good primer for the various platforms @@ -30,7 +61,7 @@ The next major thing is `pnpm` (because we're a little cooler than people who use `npm`), so check out how to install that [here](https://pnpm.io/installation). -## Install dependencies +### Install dependencies Next, install the app dependencies. @@ -43,7 +74,7 @@ $ pnpm install You'll have to re-run this occasionally when our deps change. -## Run the app +### Run the app Now you should be able to run the app in development mode: @@ -57,7 +88,7 @@ By default it will not print debug logs to console. If you want debug logs, set $ LOG_LEVEL=debug pnpm tauri dev ``` -## Lint & format +### Lint & format In order to have a PR accepted, you need to make sure everything passes our Linters, so make sure to run these before submitting. Our CI will shame you @@ -77,36 +108,40 @@ $ cargo clippy # see linting errors $ cargo fmt # format code ``` -# Debugging +--- + +## Debugging Now that you have the app running, here are some hints for debugging whatever it is that you're working on. -## Logs +### Logs The app writes logs into: 1. `stdout` in development mode 2. The Tauri [logs](https://tauri.app/v1/api/js/path/#platform-specific) directory -## Tokio +### Tokio We are also collecting tokio's runtime tracing information that could be viewed using [tokio-console](https://github.com/tokio-rs/console#tokio-console-prototypes): -- development: - ```bash - $ tokio-console - ``` -- nightly: - ```bash - $ tokio-console http://127.0.0.1:6668 - ``` -- production: - ```bash - $ tokio-console http://127.0.0.1:6667 - ``` +- development: + ```bash + $ tokio-console + ``` +- nightly: + ```bash + $ tokio-console http://127.0.0.1:6668 + ``` +- production: + ```bash + $ tokio-console http://127.0.0.1:6667 + ``` -# Building +--- + +## Building To build the app in production mode, run: @@ -116,7 +151,7 @@ $ pnpm tauri build --features devtools --config gitbutler-app/tauri.conf.nightly This will make an asset similar to our nightly build. -## Building on Windows +### Building on Windows Building on Windows is a bit of a tricky process. Here are some helpful tips. @@ -150,7 +185,7 @@ You'll need to fix the security permissions for the `nodejs` folder. 7. Make sure that `Full Control` is checked under `Allow`. 8. Apply / click OK as needed to close the dialogs. -## Perl +### Perl A Perl interpreter is required to be installed in order to configure the `openssl-sys` crate. We've used [Strawberry Perl](https://strawberryperl.com/) without issue. @@ -161,18 +196,34 @@ Note that it might appear that the build has hung or frozen on the `openssl-sys` It's not, it's just that Cargo can't report the status of a C/C++ build happening under the hood, and openssl is _large_. It'll take a while to compile. -# That's It +--- + +## Design + +We use [Figma](https://www.figma.com/) for our design work. +If you're a designer (and even if you're not), you want to contribute to the +design of GitButler, or your work involves UI, you could duplicate our design file. + +GitButler design: [Figma file 🎨](https://www.figma.com/file/FbeLt0yjY9RiNn8MXUXsYs/Client-Design?type=design&node-id=0%3A1&mode=design&t=MUDQhR3iOM3DpI9m-1) + +--- + +## Contributing Now that you're up and running, if you want to change something and open a PR for us, make sure to read [CONTRIBUTING.md](CONTRIBUTING.md) to make sure you're not wasting your time. -# Some Other Random Notes +--- + +## Some Other Random Notes Most of this is for internal GitButler use, but maybe everyone else will find it interesting too. -## Icon generation +--- + +### Icon generation I always forget how to do this, but when we update our app icon, run this to import it. @@ -181,7 +232,7 @@ import it. $ pnpm tauri icon path/to/icon.png ``` -## Release +### Release Building is done via [GitHub Action](https://github.com/gitbutlerapp/gitbutler/actions/workflows/publish.yaml). Go to the link and select `Run workflow` from the desired branch. @@ -196,9 +247,12 @@ version found at `https://app.gitbutler.com/releases`. To publish a version that you've just build, use [Release Manager](https://gitbutler.retool.com/apps/cb9cbed6-ae0a-11ed-918c-736c4335d3af/Release%20Manager). +--- + ## Development mode OAuth login By default, you will not be able to log into GitButler using Github/Google because the base url does not match. To be able to do this add ( or update ) the following line to your `.env.development` file. You will need to create the file if it does not exist. + ``` PUBLIC_API_BASE_URL=https://app.gitbutler.com/ -``` \ No newline at end of file +```