GitBook: [#9] remove line break

README.md

@@ -0,0 +1,32 @@
+# Introduction
+
+{% hint style="info" %}
+**Welcome to the Graphite beta**
+
+Everything is still a little early, so please add comments if you have any questions, feedback, or suggestions!
+{% endhint %}
+
+## What is Graphite?
+
+Graphite is an [**open source CLI**](https://github.com/screenplaydev/graphite-cli) + a [**code review dashboard**](http://app.graphite.dev) on top of GitHub that **makes** **creating & reviewing **[**stacked changes**](getting-started/why-use-stacked-changes.md)** fast & intuitive**. Anyone can start using Graphite individually without needing their coworkers to change tools - we'll seamlessly sync your code changes and reviews. We built Graphite because we missed tools like Phabricator (at Facebook) and Critique (Google) that help engineers create, approve, and ship small, incremental changes, and long-term we’re passionate about creating a powerful, modern code review experience (think Linear for CR) for fast-moving eng teams.
+
+**Got a few minutes?** Check out quick video demo from Tomas & Merrill on the Graphite team:
+
+{% embed url="https://www.youtube.com/watch?v=-EYpPlQdXH0" %}
+
+## What can you do with Graphite?
+
+With Graphite, you can:
+
+*   **Easily develop with stacked changes locally**
+
+    Graphite keeps track of your stacks and automates all of the tedious recursive rebases needed to support a stacked changes workflow.
+*   **Create and update pull requests for the branches in your stack**
+
+    Graphite makes it easy to open PRs for all branches in your stack and update them as you iterate - and we'll even add a comment to help your reviewers easily navigate to the other PRs in the stack.
+*   **View and customize inboxes for your pull requests & reviews**
+
+    Graphite's web dashboard helps you get through code review faster and focus on what's actionable with a powerful, customizable review queue with spit inboxes (i.e. "Needs your review", "Your pull requests", "Your team's pull requests").
+*   **Give thoughtful, actionable code reviews in less time \[coming soon]**
+
+    Graphite's modern, keyboard-first interface makes code review fast, intuitive, and enjoyable (with first-class support for fun features like gifs & memes/image macros)

SUMMARY.md

@@ -0,0 +1,33 @@
+# Table of contents
+
+* [Introduction](README.md)
+
+## Getting Started
+
+* [Why use stacked changes?](getting-started/why-use-stacked-changes.md)
+* [Getting started with Graphite](getting-started/getting-started-with-graphite.md)
+* [The Graphite workflow](getting-started/the-graphite-workflow.md)
+* [Privacy & security](getting-started/privacy-and-security.md)
+
+## Guides
+
+* [Graphite CLI](guides/graphite-cli/README.md)
+  * [Installing the CLI](guides/graphite-cli/installing-the-cli/README.md)
+    * [Installing without Homebrew (i.e. on Linux)](guides/graphite-cli/installing-the-cli/installing-without-homebrew-i.e.-on-linux.md)
+  * [Authenticating the CLI](guides/graphite-cli/authenticating-the-cli/README.md)
+    * [Using a GitHub Personal Access Token](guides/graphite-cli/authenticating-the-cli/using-a-github-personal-access-token.md)
+  * [Creating a stack](guides/graphite-cli/creating-a-stack.md)
+  * [Viewing a stack](guides/graphite-cli/viewing-a-stack.md)
+  * [Navigating a stack](guides/graphite-cli/navigating-a-stack.md)
+  * [Updating a mid-stack branch](guides/graphite-cli/updating-a-mid-stack-branch.md)
+  * [Creating pull requests](guides/graphite-cli/creating-pull-requests.md)
+  * [Syncing & resolving conflicts](guides/graphite-cli/syncing-and-resolving-conflicts.md)
+  * [Landing a stack](guides/graphite-cli/landing-a-stack.md)
+  * [Command shortcuts](guides/graphite-cli/command-shortcuts.md)
+  * [Mixing gt and git](guides/graphite-cli/mixing-gt-and-git.md)
+  * [CLI command reference](guides/graphite-cli/cli-command-reference.md)
+* [Graphite dashboard](guides/graphite-dashboard/README.md)
+  * [Getting started with the dashboard](guides/graphite-dashboard/getting-started-with-the-dashboard.md)
+  * [Using the review queue](guides/graphite-dashboard/using-the-review-queue.md)
+  * [Customizing the review queue](guides/graphite-dashboard/customizing-the-review-queue.md)
+  * [Reviewing code with Graphite \[alpha\]](guides/graphite-dashboard/reviewing-code-with-graphite-alpha.md)

getting-started/getting-started-with-graphite.md

@@ -0,0 +1,36 @@
+# Getting started with Graphite
+
+## Install the CLI
+
+Install the Graphite CLI using Homebrew ([https://brew.sh/](https://brew.sh))
+
+```bash
+# install Graphite from Homebrew
+brew install screenplaydev/tap/graphite
+
+# initialize Graphite
+cd ~/my-project
+gt repo init
+
+# authenticate Graphite CLI via the web dashboard (needed to create PRs)
+gt auth
+```
+
+## Sign into the Graphite dashboard
+
+1. Sign in with GitHub at [https://app.graphite.dev/](https://app.graphite.dev)
+2. Select one or more of the repos you most frequently work in
+3. Graphite will create 6 default sections of pull requests in your repos:
+   * **Needs your review** - any PRs where you (or your team) have been tagged as a reviewer
+   * **Needs your attention** - your PRs which have been approved or changes have been requested
+   * **Waiting for author** - someone else’s PRs which you (or another reviewer) have approved or requested changes on
+   * **Waiting for reviewers** - your PRs which are waiting for review
+   * **All other pull requests** - all other PRs in the repos you selected
+
+## Join the Graphite Community
+
+By using Graphite, you're joining a community of engineers at top companies around the world who have found stacked changes make them more effective at what they do.  Our Graphite Community Slack group is the best place to get support, suggest features, stay up-to-date with our latest releases, and interact with other Graphite beta users and the core team:
+
+{% embed url="https://join.slack.com/t/graphite-community/shared_invite/zt-v828g9dz-TIRvlutxTCqgZmxnsO9Knw" %}
+
+Now that you have Graphite set up, let's walk through an example of how to use the stacked changes workflow.

getting-started/privacy-and-security.md

@@ -0,0 +1,108 @@
+# Privacy & security
+
+{% hint style="info" %}
+Authenticating a new tool with your GitHub account can be scary, so we wanted to be completely transparent about how we integrate with GitHub and make sure your source code is secure.
+{% endhint %}
+
+## What data does Graphite store from the GitHub integration?
+
+tl;dr almost nothing.  We've architected our systems to use a minimal amount of data & permissions from our users (within the constraints of GitHub's API), and we'll always be fully transparent about how we use any data and permissions you grant us.
+
+### CLI
+
+Graphite does not store any user source code on its servers from the CLI. When you call `gt stack submit`, the Graphite CLI pushes the branches in your stack to the remote repo in GitHub directly from the client. The only calls from the Graphite server are made to actually open the PRs from the branches which have already been pushed to GitHub. Metadata about which branches were pushed to Github are sent to Graphite servers so we can open those PRs on your behalf.
+
+### Web dashboard
+
+Graphite does not store any source code on its servers from the web dashboard. When you open the dashboard in your browser, it calls GitHub's API directly from the client to retrieve and display pull requests in repos you have access to according to the filter views you've defined. The only data stored on Graphite servers are basic profile metadata (Github ID, username, profile picture) and the auth token generated when you sign in with GitHub, which we use to save your PR filter views and maintain your session.
+
+### Logging
+
+Graphite does not store any user source code on its servers from its logs. During normal usage of the CLI and the website, Graphite will generate and store logs to help us better debug in the event of an error and better understand the profile of our users. Examples of that data include:
+
+* Metadata about your repo: for example, number of branches or counts of Graphite commands being run. We use this to debug failing commands in the CLI (for example, in the past we found a repo with a very high number of branches would cause the CLI to hang.
+* Metadata about your usage: for example, commands being run, command runtime, or any CLI errors. We use this to understand where to further our engineering investment and understand how widespread issues are.
+* Metadata about your Github account: for example, orgs which you're a member of on Github. We use this to track the usage of our product and understand what types of orgs we work best for.
+
+***
+
+## What permissions does Graphite need from GitHub?
+
+### CLI
+
+You can use the Graphite CLI to manage stacked changes locally without authenticating with your GitHub account - the only command that you need to authenticate to run is `gt stack submit`, which needs to be able to write to the remote repo you're working in to create and/or update pull requests for each branch in your stack.
+
+To authenticate your Graphite CLI:
+
+1. Visit [https://app.graphite.dev/activate](https://app.graphite.dev/activate)
+2. Sign in with GitHub to obtain your CLI token
+3. Run `gt auth <your_token>` in your terminal
+
+### Web dashboard
+
+The [Graphite web dashboard](https://app.graphite.dev) lets you view your queue of pull requests from GitHub. In order to display your PRs, the dashboard needs to be able to read from each repo you want to display PRs for.
+
+When you sign in to the Graphite web dashboard with GitHub for the first time, you can select which organizations and repos to grant access to.
+
+## Using a GitHub Personal Access Token
+
+By default, GitHub prevents third-party applications from automatically creating API tokens for organizations. This can mean that even though you've authenticated Graphite with your GitHub account, we may not be able to generate the token needed to let you create, view, or update your pull requests (if your org has not changed this setting).
+
+For cases such as this one, where you want to give command line tools and APIs limited access to work with your account, GitHub recommends that you create and use [Personal Access Tokens](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) which do have the necessary permissions.
+
+To use a Personal Access Token with Graphite:
+
+1. Generate a new token from your [token settings page on GitHub](https://github.com/settings/tokens) with the following permissions:
+   * `repo` (for the repo you want to work in)
+   * `read:org`
+   * `read:user`
+   * `user:email`
+2. \[If your org has SSO] Check the [token settings page on GitHub](https://github.com/settings/tokens) and make sure you enable SSO for the Personal Access Token you're using with Graphite.
+3. Next, add your new token to Graphite via the [Graphite web dashboard settings page](https://app.graphite.dev/settings).
+
+Once your token is added, you should be able to do the following:
+
+* Select your repo from the dropdowns in each section of the Graphite web dashboard
+* Run `gt stack submit` in the Graphite CLI to create pull requests in GitHub for every branch in your stack
+
+If this still doesn't resolve your issue, please ping us on Slack so we can troubleshoot!
+
+***
+
+## What happens if Graphite's GitHub integration changes?
+
+### Process for upcoming changes
+
+We're iterating on Graphite rapidly, but we'll always over-communicate when it comes to how we interact with your source code from GitHub. If we intend to change the architecture or scope of our GitHub integration in the future relating to source code, we'll give you at least 7 days notice prior to making any changes. Furthermore, if we require additional scopes of access from GitHub, you'll be prompted to sign in again with your account and confirm that you want to grant the additional permissions we've requested.
+
+***
+
+### Upcoming changes on our roadmap
+
+In the spirit of transparency, we want to keep you up-to-date on any changes we're currently working on that will change the scope of our integration.
+
+#### Actions from the web dashboard
+
+We soon hope to be able to let developers take actions directly from our dashboard. Two examples of such actions are "land all" (landing multiple dependent PRs) and "revert". In order to enable this functionality, once you press a button to take one of those actions we will spin up an ephemeral container, clone your repo onto it, take the desired action, push the change to Github, and then securely delete the container. Taking this action will clone your source code onto our server, but we will not persist it.
+
+#### Caching
+
+In an effort to reduce our usage of the Github API, we may start caching requests (storing the relevant information on our server). At the moment, we are only intending to cache metadata (e.g. repos which you could access, or information about members of your org to display in hover cards), and we are not intending to cache source code, although we will let you know if this changes.
+
+***
+
+## How does Graphite keep my source code safe?
+
+We understand how important it is to keep your source code safe - that's why we built Graphite with security & privacy best practices from day 1.  We're more than happy to provide you with the following company policies to give you a better sense of how we approach security at Graphite:
+
+* Security Program Overview
+* Data Protection Policy
+* Security Incident Response Plan
+* Encryption Policy
+* Vulnerability & Patch Management Policy
+* Identity Access Management Policy
+* Secure Software Development Policy
+* System Audit Policy
+* Business Continuity & Disaster Recovery Policy
+
+Please email [**[email protected]**](mailto:[email protected]) to request copies, or feel free to share your team's security questionnaire if you have a standard format.

getting-started/the-graphite-workflow.md

@@ -0,0 +1,151 @@
+# The Graphite workflow
+
+{% hint style="info" %}
+Now that you've set up your CLI & web dashboard, it's time to get familiar with the core Graphite development workflow.
+{% endhint %}
+
+Let’s say you’re starting work on a new feature (i.e. adding stories to Instagram), which involves API, server, and front-end changes…
+
+![](<../.gitbook/assets/architecture diagram.png>)
+
+Today, you’d probably create one large “stories” feature branch with changes across all 3 surfaces…
+
+![](<../.gitbook/assets/00 big PR.png>)
+
+…but with stacked changes, you can break up your changes into smaller branches which are easier to review:
+
+![](<../.gitbook/assets/00 stacked prs.png>)
+
+You would start by creating your first branch:
+
+```bash
+# check out your trunk branch
+gt branch checkout main
+
+# * build Stories API *
+
+# create a new branch off of main with your changes and add a commit
+gt add -A # add all unstaged change (same syntax as git add)
+gt branch create feat-stories-API # -> creates a branch named feat-stories-API
+gt commit create -m "Stories - API [1/3]" # -> creates a commit with message "Stories - API [1/3]" - use -a to stage all unstaged changes
+
+# alternatively, you can combine the last 3 commands into a single line:
+gt branch create -a feat-stories-API -m "Stories - API [1/3]"
+```
+
+![](<../.gitbook/assets/01 new branch.png>)
+
+Note that unlike a standard git workflow - where you create a new branch before working on your feature - with `gt` you do the following:
+
+1. Start by building your feature on an existing branch
+2. Add your unstaged changes with `gt add`
+3. Create a new branch with `gt branch create`
+
+Graphite keeps track of the parent branch so that it can always fix your stacks if something changes underneath.
+
+```bash
+# view your current stacks as tracked by Graphite
+gt log # (log view)
+gt log short # (compact view of just stacks)
+```
+
+![](<../.gitbook/assets/01a highlight meta.png>)
+
+You can then submit your branch for review when you’re done the API portion…
+
+```bash
+# submit your current stack to GitHub, creating or updating PRs for each branch as necessary
+gt stack submit
+
+# view your currrent stacks
+gt log
+```
+
+![](<../.gitbook/assets/02 put up PR.png>)
+
+…and continue to work by creating more stacked changes as your first PR is being reviewed.
+
+```bash
+# * build Stories server *
+
+# create a new branch off of feat-stories-api and add a commit
+gt branch create -a feat-stories-server -m "Stories - server [2/3]"
+
+# * build Stories frontend *
+
+# create a new branch off of feat-stories-server and add a commit
+gt branch create -a feat-stories-frontend -m "Stories - frontend [3/3]"
+
+# view your currrent stacks
+gt log
+```
+
+![](<../.gitbook/assets/04 stack branches.png>)
+
+After your PR is approved, it can be merged in.
+
+```bash
+# * merge in your changes on GitHub or the Graphite web dashboard [coming soon] *
+```
+
+![](<../.gitbook/assets/05 first PR approved.png>)
+
+Whenever you merge a PR into `remote/main`, you can sync Graphite to make sure the parent branch info for your local repo stays up to date with the remote repo…
+
+```bash
+# pull in the latest trunk branch from remote, delete local branches which were merged in, and recursively rebase upstack branches which have not been merged
+gt repo sync
+
+# view your current stacks
+gt log
+```
+
+![](<../.gitbook/assets/06 merge first PR.png>)
+
+…and then continue to work on your stacked changes without worrying about conflicts.
+
+![](<../.gitbook/assets/07 updating meta.png>)
+
+You can also submit multiple changes at a time for review and approval:
+
+```bash
+# navigate to the top of the stack
+gt branch checkout main
+gt branch next 2 # -> checks out the branch 2 levels upstack (in this case feat-stories-frontend)
+
+# submit the current branch and all downstack branches to GitHub for review
+gt stack submit
+
+# view your current stacks
+gt log
+```
+
+![](<../.gitbook/assets/08 stack approved (2).png>)
+
+Whenever you push a stack of PRs to GitHub, Graphite automatically adds a comment to every PR in the stack to help your reviewers navigate between them:
+
+![](https://s3.us-west-2.amazonaws.com/secure.notion-static.com/dd938ce0-5330-4fd1-8806-f2a55f7009b4/Screen\_Shot\_2021-09-21\_at\_10.35.14\_AM.png?X-Amz-Algorithm=AWS4-HMAC-SHA256\&X-Amz-Credential=AKIAT73L2G45O3KS52Y5%2F20211013%2Fus-west-2%2Fs3%2Faws4\_request\&X-Amz-Date=20211013T231257Z\&X-Amz-Expires=86400\&X-Amz-Signature=f91c505f8e30f773b5e9d0ff7836c67e8070a4ce2663a45f0482d627a20edf40\&X-Amz-SignedHeaders=host\&response-content-disposition=filename%20%3D%22Screen%2520Shot%25202021-09-21%2520at%252010.35.14%2520AM.png%22)
+
+Once all the PRs in your stack have been approved, you can merge them all into trunk (see [Landing a stack of branches](https://www.notion.so/Graphite-user-guide-66300dcb2d29453fb1d6ea013a8d4859) for more on this).
+
+![](<../.gitbook/assets/09 merge stack.png>)
+
+Graphite makes it easy to continue building without interruptions - just sync your repo, start working on your next feature, and then start a new stack by creating a branch.
+
+```bash
+# pull in the latest trunk branch from remote, delete local branches which were merged in, and recursively rebase upstack branches which have not been merged
+gt repo sync
+gt branch checkout main
+
+# * work on update to stories *
+
+# create a new branch off of feat-stories-server
+gt branch create -a feat-stories-update -m "Stories - update"
+
+# view your current stacks
+gt log
+```
+
+![](<../.gitbook/assets/10 new branch.png>)
+
+Now that you have a sense of how to build using the stacked changes workflow with Graphite, feel free to explore our detailed documentation and start creating stacks!