Skip to content

Commit 7186430

Browse files
schacongitbutler-client
schacon
authored and
gitbutler-client
committed
add a bunch of basic docs that we need for open sourcing this bad boy
1 parent 8db28ea commit 7186430

6 files changed

+532
-125
lines changed

‎CODE_OF_CONDUCT.md

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to making participation in our project and
7+
our community a harassment-free experience for everyone, regardless of age, body
8+
size, disability, ethnicity, gender identity and expression, level of experience,
9+
nationality, personal appearance, race, religion, or sexual identity and
10+
orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
- Using welcoming and inclusive language
18+
- Being respectful of differing viewpoints and experiences
19+
- Gracefully accepting constructive criticism
20+
- Focusing on what is best for the community
21+
- Showing empathy towards other community members
22+
23+
Examples of unacceptable behavior by participants include:
24+
25+
- The use of sexualized language or imagery and unwelcome sexual attention or
26+
advances
27+
- Trolling, insulting/derogatory comments, and personal or political attacks
28+
- Public or private harassment
29+
- Publishing others' private information, such as a physical or electronic
30+
address, without explicit permission
31+
- Other conduct which could reasonably be considered inappropriate in a
32+
professional setting
33+
- Attempting to contact maintainers outside of GitHub.com without an explicit
34+
invitation to do so.
35+
36+
## Our Responsibilities
37+
38+
Project maintainers are responsible for clarifying the standards of acceptable
39+
behavior and are expected to take appropriate and fair corrective action in
40+
response to any instances of unacceptable behavior.
41+
42+
Project maintainers have the right and responsibility to remove, edit, or
43+
reject comments, commits, code, wiki edits, issues, and other contributions
44+
that are not aligned to this Code of Conduct, or to ban temporarily or
45+
permanently any contributor for other behaviors that they deem inappropriate,
46+
threatening, offensive, or harmful.
47+
48+
## Scope
49+
50+
This Code of Conduct applies both within project spaces and in public spaces
51+
when an individual is representing the project or its community. Examples of
52+
representing a project or community include using an official project e-mail
53+
address, posting via an official social media account, or acting as an appointed
54+
representative at an online or offline event. Representation of a project may be
55+
further defined and clarified by project maintainers.
56+
57+
## Enforcement
58+
59+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
60+
reported by contacting the project team at [email protected]. All
61+
complaints will be reviewed and investigated and will result in a response that
62+
is deemed necessary and appropriate to the circumstances. The project team is
63+
obligated to maintain confidentiality with regard to the reporter of an incident.
64+
Further details of specific enforcement policies may be posted separately.
65+
66+
Project maintainers who do not follow or enforce the Code of Conduct in good
67+
faith may face temporary or permanent repercussions as determined by other
68+
members of the project's leadership.
69+
70+
## Attribution
71+
72+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
73+
available at [http://contributor-covenant.org/version/1/4][version]
74+
75+
[homepage]: http://contributor-covenant.org
76+
[version]: http://contributor-covenant.org/version/1/4/

‎CONTRIBUTING.md

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Contributing to GitButler
2+
3+
So you're interested in contributing to GitButler. Amazing!
4+
5+
## Understand the License
6+
7+
First thing to know, GitButler is not a side project, it is the product of a
8+
pretty cool company located in Berlin who develop this client and it's
9+
associated services professionally. For this reason, we have licensed this
10+
software under the [Functional Source License](https://fsl.software/), a
11+
mostly permissive non-compete license that converts to Apache 2.0 or MIT after
12+
two years.
13+
14+
So, it's not strictly OSS, but it _will_ be. You're free to contribute,
15+
but you can't take this and use it to compete with us. You can, however,
16+
otherwise use it however you want.
17+
18+
We figured this is better than closed source while still letting us make a
19+
living from our hard work without worrying too much about bad actors.
20+
21+
## Our Development Process
22+
23+
As a private company, we have our own development processes that we try to be
24+
fairly open about, but we're all sitting in a room in Berlin, so external
25+
contributions and remote work aren't really a central part of our process.
26+
27+
It's possible that you want to see a feature and we disagree, so if you want
28+
to get something accepted, please discuss it with us first so we can all be
29+
fairly confident that your work has a chance to be accepted before you spend
30+
your time or result in needing to maintain a fork.
31+
32+
The two places to communicate with us are on Discord and GitHub (issues and
33+
discussions, etc).
34+
35+
Join our Discord here: https://discord.gg/MmFkmaJ42D
36+
37+
## Submitting a Bug Report
38+
39+
You probably know how to submit a bug report.
40+
41+
You know, check first to see if something is already there, give us detail to
42+
recreate it if at all possible. Things you would want you to do if you were
43+
maintaining this project.
44+
45+
## Submitting a Change
46+
47+
If you talked it over with us and we agree that it's something we would take,
48+
please do the familiar GitHub dance of forking the repository and submitting
49+
a Pull Request so we can review and possibly merge it.
50+
51+
Any contributions sent to us implicitly give us the right to redistribute that
52+
work under the same license and rights.
53+
54+
[Why we don't explicity require a CLA for contributions to GitButler](https://ben.balter.com/2018/01/02/why-you-probably-shouldnt-add-a-cla-to-your-open-source-project/)
55+
56+
## How will GitButler Stay in Business?
57+
58+
The client is open source and free to use, forever. If you want to use this
59+
as your Git client, it will never be pulled out from under you.
60+
61+
In parallel with this client, we're also developing some rad cloud services
62+
that you can optionally enable but are not neccesary or limiting to your
63+
client experience. If we can provide some compelling team functionality that
64+
you can get your boss to pay for, then we would love to have your business
65+
in that area. If it's not interesting to you, then never fear, the client is
66+
fully functional on it's own and totally free.
67+
68+
## Kudos
69+
70+
We _love_ our community. Whether you just join Discord to give us some feedback,
71+
file a well researched issue, or submit a killer PR, we are excited that you
72+
care about what we're doing.
73+
74+
However, helping us with our codebase is over the top. We'll call out our
75+
contributors in some way, though we haven't quite figured out how yet. But
76+
rest assured, we'll give you credit. Or schwag maybe. Or a beer, if you're
77+
ever in town.
78+
79+
## Get into the Code!
80+
81+
Ok, you're officially onboarded. Grab the code and start in on the
82+
[DEVELOPMENT.md](DEVELOPMENT.md) file.
83+
84+
God speed.

‎DEVELOPMENT.md

+197
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# How to Hack on GitButler
2+
3+
Alrighty, you want to get compiling. We love you already. Your parents raised
4+
you right. Let's get started.
5+
6+
# Overview
7+
8+
So how does this whole thing work?
9+
10+
It's a [Tauri app](https://tauri.app/), which is basically like an Electron app,
11+
in that we can develop a desktop app from one source with multiple OS targets
12+
and write the UI in HTML and Javascript. Except instead of Node for the
13+
filesystem access part, Tauri uses [Rust](https://www.rust-lang.org/).
14+
15+
So everything that hits disk is in Rust, everything that the
16+
user sees is in HTML/JS. Specifically we use [Svelte](https://svelte.dev/)
17+
in Typescript for that layer.
18+
19+
# The Basics
20+
21+
OK, let's get it running.
22+
23+
## Prerequisites
24+
25+
First of all, this is a Tauri app, which is a Rust app. So go install Rust.
26+
The Tauri site has a good primer for the various platforms
27+
[here](https://tauri.app/v1/guides/getting-started/prerequisites).
28+
29+
The next major thing is `pnpm` (because we're a little cooler than people who
30+
use `npm`), so check out how to install that
31+
[here](https://pnpm.io/installation).
32+
33+
## Install dependencies
34+
35+
Next, install the app dependencies.
36+
37+
I hope you have some disk space for 300M of `node_modules`, because this bad
38+
boy will fill er up:
39+
40+
```bash
41+
$ pnpm install
42+
```
43+
44+
You'll have to re-run this occasionally when our deps change.
45+
46+
## Run the app
47+
48+
Now you should be able to run the app in development mode:
49+
50+
```bash
51+
$ pnpm tauri dev
52+
```
53+
54+
By default it will not print debug logs to console. If you want debug logs, set `LOG_LEVEL` environment variable:
55+
56+
```bash
57+
$ LOG_LEVEL=debug pnpm tauri dev
58+
```
59+
60+
## Lint & format
61+
62+
In order to have a PR accepted, you need to make sure everything passes our
63+
Linters, so make sure to run these before submitting. Our CI will shame you
64+
if you don't.
65+
66+
Javascript:
67+
68+
```bash
69+
$ pnpm lint
70+
$ pnpm format
71+
```
72+
73+
Rust:
74+
75+
```bash
76+
$ cargo clippy # see linting errors
77+
$ cargo fmt # format code
78+
```
79+
80+
# Debugging
81+
82+
Now that you have the app running, here are some hints for debugging whatever
83+
it is that you're working on.
84+
85+
## Logs
86+
87+
The app writes logs into:
88+
89+
1. `stdout` in development mode
90+
2. The Tauri [logs](https://tauri.app/v1/api/js/path/#platform-specific) directory
91+
92+
## Tokio
93+
94+
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):
95+
96+
- developlent:
97+
```bash
98+
$ tokio-console
99+
```
100+
- nightly:
101+
```bash
102+
$ tokio-console http://127.0.0.1:6668
103+
```
104+
- production:
105+
```bash
106+
$ tokio-console http://127.0.0.1:6667
107+
```
108+
109+
# Building
110+
111+
To build the app in production mode, run:
112+
113+
```bash
114+
$ pnpm tauri build --features devtools --config gitbutler-app/tauri.conf.nightly.json
115+
```
116+
117+
This will make an asset similar to our nightly build.
118+
119+
## Building on Windows
120+
121+
Building on Windows is a bit of a tricky process. Here are some helpful tips.
122+
123+
### File permissions
124+
125+
We use `pnpm`, which requires a relatively recent version of Node.js.
126+
Make sure that the latest stable version of Node.js is installed and
127+
on the PATH, and then `npm i -g pnpm`.
128+
129+
This often causes file permissions. First, the AppData folder may not
130+
be present. Be sure to create it if it isn't.
131+
132+
```
133+
mkdir %APPDATA%\npm
134+
```
135+
136+
Secondly, typically folders within `Program Files` are not writable.
137+
You'll need to fix the security permissions for the `nodejs` folder.
138+
139+
> **NOTE:** Under specific circumstances, depending on your usage of
140+
> Node.js, this may pose a security concern. Be sure to understand
141+
> the implications of this before proceeding.
142+
143+
1. Right click on the `nodejs` folder in `Program Files`.
144+
2. Click on `Properties`.
145+
3. Click on the `Security` tab.
146+
4. Click on `Edit` next to "change permissions".
147+
5. Click on `Add`.
148+
6. Type in the name of your user account, or type `Everyone` (case-sensitive).
149+
Click `Check Names` to verify (they will be underlined if correct).
150+
7. Make sure that `Full Control` is checked under `Allow`.
151+
8. Apply / click OK as needed to close the dialogs.
152+
153+
## Perl
154+
155+
A Perl interpreter is required to be installed in order to configure the `openssl-sys`
156+
crate. We've used [Strawberry Perl](https://strawberryperl.com/) without issue.
157+
Make sure it's installed and `perl` is available on the `PATH` (it is by default
158+
after installation, just make sure to restart the terminal after installing).
159+
160+
Note that it might appear that the build has hung or frozen on the `openssl-sys` crate.
161+
It's not, it's just that Cargo can't report the status of a C/C++ build happening
162+
under the hood, and openssl is _large_. It'll take a while to compile.
163+
164+
# That's It
165+
166+
Now that you're up and running, if you want to change something and open a PR
167+
for us, make sure to read [CONTRIBUTING.md](CONTRIBUTING.md) to make sure you're
168+
not wasting your time.
169+
170+
# Some Other Random Notes
171+
172+
Most of this is for internal GitButler use, but maybe everyone else will find
173+
it interesting too.
174+
175+
## Icon generation
176+
177+
I always forget how to do this, but when we update our app icon, run this to
178+
import it.
179+
180+
```bash
181+
$ pnpm tauri icon path/to/icon.png
182+
```
183+
184+
## Release
185+
186+
Building is done via [GitHub Action](https://github.com/gitbutlerapp/gitbutler-client/actions/workflows/publish.yaml).
187+
Go to the link and select `Run workflow` from the desired branch.
188+
189+
### Versioning
190+
191+
When running the [release action](https://github.com/gitbutlerapp/gitbutler-client/actions/workflows/publish.yaml),
192+
you will have to choose one of `major`, `minor`, or `patch` release type. Action will generate a new version based on your input and current
193+
version found at `https://app.gitbutler.com/releases`.
194+
195+
### Publishing
196+
197+
To publish a version that you've just build, use [Release Manager](https://gitbutler.retool.com/apps/cb9cbed6-ae0a-11ed-918c-736c4335d3af/Release%20Manager).

0 commit comments

Comments
 (0)