gitbutlerapp/gitbutler
1
1
Fork 0
mirror of https://github.com/gitbutlerapp/gitbutler.git synced 2024-11-22 11:02:11 +03:00
Code Issues Packages Projects Releases Wiki Activity

add a bunch of basic docs that we need for open sourcing this bad boy

Browse Source
This commit is contained in:
Scott Chacon 2024-01-11 19:52:52 +01:00 committed by GitButler
parent 8db28ea0e3
commit 718643022b
6 changed files with 532 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
CODE_OF_CONDUCT.md Normal file
View File

@ -0,0 +1,76 @@
# Contributor Covenant Code of Conduct
## Our Pledge
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience,
nationality, personal appearance, race, religion, or sexual identity and
orientation.
## Our Standards
Examples of behavior that contributes to creating a positive environment
include:
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
- The use of sexualized language or imagery and unwelcome sexual attention or
advances
- Trolling, insulting/derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or electronic
address, without explicit permission
- Other conduct which could reasonably be considered inappropriate in a
professional setting
- Attempting to contact maintainers outside of GitHub.com without an explicit
invitation to do so.
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at opensource@gitbutler.com. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at [http://contributor-covenant.org/version/1/4][version]
[homepage]: http://contributor-covenant.org
[version]: http://contributor-covenant.org/version/1/4/

84
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,84 @@
# Contributing to GitButler
So you're interested in contributing to GitButler. Amazing!
## Understand the License
First thing to know, GitButler is not a side project, it is the product of a
pretty cool company located in Berlin who develop this client and it's
associated services professionally. For this reason, we have licensed this
software under the [Functional Source License](https://fsl.software/), a
mostly permissive non-compete license that converts to Apache 2.0 or MIT after
two years.
So, it's not strictly OSS, but it _will_ be. You're free to contribute,
but you can't take this and use it to compete with us. You can, however,
otherwise use it however you want.
We figured this is better than closed source while still letting us make a
living from our hard work without worrying too much about bad actors.
## Our Development Process
As a private company, we have our own development processes that we try to be
fairly open about, but we're all sitting in a room in Berlin, so external
contributions and remote work aren't really a central part of our process.
It's possible that you want to see a feature and we disagree, so if you want
to get something accepted, please discuss it with us first so we can all be
fairly confident that your work has a chance to be accepted before you spend
your time or result in needing to maintain a fork.
The two places to communicate with us are on Discord and GitHub (issues and
discussions, etc).
Join our Discord here: https://discord.gg/MmFkmaJ42D
## Submitting a Bug Report
You probably know how to submit a bug report.
You know, check first to see if something is already there, give us detail to
recreate it if at all possible. Things you would want you to do if you were
maintaining this project.
## Submitting a Change
If you talked it over with us and we agree that it's something we would take,
please do the familiar GitHub dance of forking the repository and submitting
a Pull Request so we can review and possibly merge it.
Any contributions sent to us implicitly give us the right to redistribute that
work under the same license and rights.
[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/)
## How will GitButler Stay in Business?
The client is open source and free to use, forever. If you want to use this
as your Git client, it will never be pulled out from under you.
In parallel with this client, we're also developing some rad cloud services
that you can optionally enable but are not neccesary or limiting to your
client experience. If we can provide some compelling team functionality that
you can get your boss to pay for, then we would love to have your business
in that area. If it's not interesting to you, then never fear, the client is
fully functional on it's own and totally free.
## Kudos
We _love_ our community. Whether you just join Discord to give us some feedback,
file a well researched issue, or submit a killer PR, we are excited that you
care about what we're doing.
However, helping us with our codebase is over the top. We'll call out our
contributors in some way, though we haven't quite figured out how yet. But
rest assured, we'll give you credit. Or schwag maybe. Or a beer, if you're
ever in town.
## Get into the Code!
Ok, you're officially onboarded. Grab the code and start in on the
[DEVELOPMENT.md](DEVELOPMENT.md) file.
God speed.

197
DEVELOPMENT.md Normal file
View File

@ -0,0 +1,197 @@
# How to Hack on GitButler
Alrighty, you want to get compiling. We love you already. Your parents raised
you right. Let's get started.
# Overview
So how does this whole thing work?
It's a [Tauri app](https://tauri.app/), which is basically like an Electron app,
in that we can develop a desktop app from one source with multiple OS targets
and write the UI in HTML and Javascript. Except instead of Node for the
filesystem access part, Tauri uses [Rust](https://www.rust-lang.org/).
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
OK, let's get it running.
## 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
[here](https://tauri.app/v1/guides/getting-started/prerequisites).
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
Next, install the app dependencies.
I hope you have some disk space for 300M of `node_modules`, because this bad
boy will fill er up:
```bash
$ pnpm install
```
You'll have to re-run this occasionally when our deps change.
## Run the app
Now you should be able to run the app in development mode:
```bash
$ pnpm tauri dev
```
By default it will not print debug logs to console. If you want debug logs, set `LOG_LEVEL` environment variable:
```bash
$ LOG_LEVEL=debug pnpm tauri dev
```
## 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
if you don't.
Javascript:
```bash
$ pnpm lint
$ pnpm format
```
Rust:
```bash
$ cargo clippy # see linting errors
$ cargo fmt # format code
```
# Debugging
Now that you have the app running, here are some hints for debugging whatever
it is that you're working on.
## 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
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):
- developlent:
```bash
$ tokio-console
```
- nightly:
```bash
$ tokio-console http://127.0.0.1:6668
```
- production:
```bash
$ tokio-console http://127.0.0.1:6667
```
# Building
To build the app in production mode, run:
```bash
$ pnpm tauri build --features devtools --config gitbutler-app/tauri.conf.nightly.json
```
This will make an asset similar to our nightly build.
## Building on Windows
Building on Windows is a bit of a tricky process. Here are some helpful tips.
### File permissions
We use `pnpm`, which requires a relatively recent version of Node.js.
Make sure that the latest stable version of Node.js is installed and
on the PATH, and then `npm i -g pnpm`.
This often causes file permissions. First, the AppData folder may not
be present. Be sure to create it if it isn't.
```
mkdir %APPDATA%\npm
```
Secondly, typically folders within `Program Files` are not writable.
You'll need to fix the security permissions for the `nodejs` folder.
> **NOTE:** Under specific circumstances, depending on your usage of
> Node.js, this may pose a security concern. Be sure to understand
> the implications of this before proceeding.
1. Right click on the `nodejs` folder in `Program Files`.
2. Click on `Properties`.
3. Click on the `Security` tab.
4. Click on `Edit` next to "change permissions".
5. Click on `Add`.
6. Type in the name of your user account, or type `Everyone` (case-sensitive).
Click `Check Names` to verify (they will be underlined if correct).
7. Make sure that `Full Control` is checked under `Allow`.
8. Apply / click OK as needed to close the dialogs.
## 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.
Make sure it's installed and `perl` is available on the `PATH` (it is by default
after installation, just make sure to restart the terminal after installing).
Note that it might appear that the build has hung or frozen on the `openssl-sys` crate.
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
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
Most of this is for internal GitButler use, but maybe everyone else will find
it interesting too.
## Icon generation
I always forget how to do this, but when we update our app icon, run this to
import it.
```bash
$ pnpm tauri icon path/to/icon.png
```
## Release
Building is done via [GitHub Action](https://github.com/gitbutlerapp/gitbutler-client/actions/workflows/publish.yaml).
Go to the link and select `Run workflow` from the desired branch.
### Versioning
When running the [release action](https://github.com/gitbutlerapp/gitbutler-client/actions/workflows/publish.yaml),
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
version found at `https://app.gitbutler.com/releases`.
### Publishing
To publish a version that you've just build, use [Release Manager](https://gitbutler.retool.com/apps/cb9cbed6-ae0a-11ed-918c-736c4335d3af/Release%20Manager).

114
LICENSE.md Normal file
View File

@ -0,0 +1,114 @@
# Functional Source License, Version 1.0, MIT Change License
## Abbreviation
FSL-1.0-MIT
## Notice
Copyright 2024 GitButler Inc
## Terms and Conditions
### Licensor ("We")
The party offering the Software under these Terms and Conditions.
### The Software
The "Software" is each version of the software that we make available under
these Terms and Conditions, as indicated by our inclusion of these Terms and
Conditions with the Software.
### License Grant
Subject to your compliance with this License Grant and the Patents,
Redistribution and Trademark clauses below, we hereby grant you the right to
use, copy, modify, create derivative works, publicly perform, publicly display
and redistribute the Software for any Permitted Purpose identified below.
### Permitted Purpose
A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
means use of the Software in or for a commercial product or service that
competes with the Software or any other product or service we offer using the
Software as of the date we make the Software available.
Competing Uses specifically include using the Software:
1. as a substitute for any of our products or services;
2. in a way that exposes the APIs of the Software; and
3. in a product or service that offers the same or substantially similar
functionality to the Software.
Permitted Purposes specifically include using the Software:
1. for your internal use and access;
2. for non-commercial education;
3. for non-commercial research; and
4. in connection with software development services or managed services that
you provide to a licensee using the Software in accordance with these Terms
and Conditions.
### Patents
To the extent your use for a Permitted Purpose would necessarily infringe our
patents, the license grant above includes a license under our patents. If you
make a claim against any party that the Software infringes or contributes to
the infringement of any patent, then your patent license to the Software ends
immediately.
### Redistribution
The Terms and Conditions apply to all copies, modifications and derivatives of
the Software.
If you redistribute any copies, modifications or derivatives of the Software,
you must include a copy of or a link to these Terms and Conditions and not
remove any copyright notices provided in or with the Software.
### Disclaimer
THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
### Trademarks
Except for displaying the License Details and identifying us as the origin of
the Software, you have no right under these Terms and Conditions to use our
trademarks, trade names, service marks or product names.
## Change License
On the second anniversary of the date we make the Software available, the
Software will become available under the MIT license. On that date, the Terms
and Conditions above automatically terminate and the following terms become
effective:
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

171
README.md
View File

@ -1,146 +1,67 @@
# Development # [GitButler](https://gitbutler.com)
## Prerequisites <img width="200px" src="https://app.gitbutler.com/assets/gb-logo-c5e20a2be4fe4a7d2dbc8b5c0048782608bb5dbc58b7343cd5e7a49183ff961e.svg" />
[see here](https://tauri.app/v1/guides/getting-started/prerequisites) [![CI][s0]][l0] [![TWEET][s6]][l6]
for the list of software required to build / develope the app.
### Setup [s0]: https://github.com/gitbutlerapp/gitbutler-client/actions/workflows/push.yaml/badge.svg
[l0]: https://github.com/gitbutlerapp/gitbutler-client/actions/workflows/push.yaml
[s6]: https://img.shields.io/twitter/follow/gitbutler?label=follow&style=social
[l6]: https://twitter.com/intent/follow?screen_name=gitbutler
Then, make sure to install app dependencies: **[GitButler](https://gitbutler.com) is a new approach to version control tooling, using Git as a backend**
```bash It is an open source [Tauri](https://tauri.app/)-based
$ pnpm install Git client. It's UI is written in [Svelte](https://svelte.dev/) using [TypeScript](https://www.typescriptlang.org)
``` and it's backend is written in [Rust](https://www.rust-lang.org/).
### Run the app ![gitbutler_client](https://github.com/gitbutlerapp/gitbutler-client/assets/70/89466226-fc0b-4d42-951c-67d95590e00c)
Now you should be able to run the app in development mode: ## Downloading a Build
```bash You can download the newest client build from [our downloads page](https://app.gitbutler.com/downloads).
$ pnpm tauri dev
```
By default it will not print debug logs to console. If you want debug logs, set `LOG_LEVEL` environment variable: Currently we have builds for Mac and Linux. A Windows build is on the way.
```bash ## Why GitButler?
$ LOG_LEVEL=debug pnpm tauri dev
```
### Lint & format Git's user interface has hardly been touched for 15 years. While it was written
for Linux kernel devs sending patches to each other over mailing lists, most
modern developers have different workflows and needs.
Javascript: GitButler aims to rethink the version control concept, while still storing data
in Git and being able to push trees to Git servers.
```bash ## Main Features
$ pnpm lint
$ pnpm format
```
Rust: - **Virtual Branches**
- Organize work on multiple branches simultaneously, rather than constantly switching branches
- Automatically create new branches when needed
- **Easy Commit Management**
- Undo, Amend and Squash commits by dragging and dropping
- **GitHub Integration**
- Authenticate to GitHub to open Pull Requests, list branches and statuses and more
- **Easy SSH Key Management**
- GitButler can generate an SSH key to upload to GitHub automatically
- **AI Tools**
- Automatically write commit messages based on your work in progress
- Automatically create descriptive branch names
- **Commit Signing**
- Easy commit signing with our generated SSH key
```bash ## Documentation
$ cargo clippy # see linting errors
$ cargo fmt # format code
```
## Debug You can find our end user documentation at: https://docs.gitbutler.com
### Logs ## Bugs and Feature Requests
App writes logs into: If you have a bug or feature request, feel free to open an [issue](https://github.com/gitbutlerapp/gitbutler-client/issues/new),
or [join our Discord server](https://discord.gg/wDKZCPEjXC).
1. stdout in development mode ## Contributing
2. [Logs](https://tauri.app/v1/api/js/path/#platform-specific) directory
### Tokio So you want to help out? Please check out the [CONTRIBUTING.md](CONTRIBUTING.md)
document.
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): If you want to skip right to getting the code to actually compile, take a look
at the [DEVELOPMENT.md](DEVELOPMENT.md) file.
- developlent:
```bash
$ tokio-console
```
- nightly:
```bash
$ tokio-console http://127.0.0.1:6668
```
- production:
```bash
$ tokio-console http://127.0.0.1:6667
```
## Build
To build the app in production mode, run:
```bash
$ pnpm tauri build --features devtools --config gitbutler-app/tauri.conf.nightly.json
```
This will make an asset similar to our nightly build.
### Building on Windows
Building on Windows is a bit of a tricky process. Here are some helpful tips.
#### File permissions
We use `pnpm`, which requires a relatively recent version of Node.js.
Make sure that the latest stable version of Node.js is installed and
on the PATH, and then `npm i -g pnpm`.
This often causes file permissions. First, the AppData folder may not
be present. Be sure to create it if it isn't.
```
mkdir %APPDATA%\npm
```
Secondly, typically folders within `Program Files` are not writable.
You'll need to fix the security permissions for the `nodejs` folder.
> **NOTE:** Under specific circumstances, depending on your usage of
> Node.js, this may pose a security concern. Be sure to understand
> the implications of this before proceeding.
1. Right click on the `nodejs` folder in `Program Files`.
2. Click on `Properties`.
3. Click on the `Security` tab.
4. Click on `Edit` next to "change permissions".
6. Click on `Add`.
7. Type in the name of your user account, or type `Everyone` (case-sensitive).
Click `Check Names` to verify (they will be underlined if correct).
8. Make sure that `Full Control` is checked under `Allow`.
8. Apply / click OK as needed to close the dialogs.
### 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.
Make sure it's installed and `perl` is available on the `PATH` (it is by default
after installation, just make sure to restart the terminal after installing).
Note that it might appear that the build has hung or frozen on the `openssl-sys` crate.
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.
## Icon generation
```bash
$ pnpm tauri icon path/to/icon.png
```
## Release
Building is done via [GitHub Action](https://github.com/gitbutlerapp/gitbutler-client/actions/workflows/publish.yaml).
Go to the link and select `Run workflow` from the desired branch.
### Versioning
When running the [release action](https://github.com/gitbutlerapp/gitbutler-client/actions/workflows/publish.yaml),
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
version found at `https://app.gitbutler.com/releases`.
### Publishing
To publish a version that you've just build, use [Release Manager](https://gitbutler.retool.com/apps/cb9cbed6-ae0a-11ed-918c-736c4335d3af/Release%20Manager).

15
SECURITY.md Normal file
View File

@ -0,0 +1,15 @@
GitButler takes the security of our software products and services seriously.
If you believe you have found a security vulnerability in this GitButler-owned
open source repository you can report it to us directly using [private vulnerability reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability).
For reporting vulnerabilities of any other GitButler service or application,
please email us directly at security@gitbutler.com
For severe vulnerabilities, we will provide rewards from $100 up to $10,000 USD
depending on the severity of the vulnerability.
**Please do not report security vulnerabilities through public GitHub issues,
discussions, or pull requests.**
Thanks for helping make GitButler safe for everyone.