[WIP] New Handbook Project

handbook-new/.gitignore

@@ -0,0 +1,34 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# vercel
+.vercel

handbook-new/content/engineering/developer-insights/index.mdx

@@ -0,0 +1,6 @@
+---
+title: "Developer Insights Org"
+description: "Developer Insights Org"
+---
+
+# Developer Insights Org

handbook-new/content/engineering/index.mdx

@@ -0,0 +1,91 @@
+---
+title: "Engineering"
+description: "Engineering Department"
+---
+
+
+- [Onboarding](onboarding.md)
+- [Principles and practices](principles-and-practices.md)
+- RFCs (requests for comment)
+  - [All RFC documents](https://drive.google.com/drive/folders/1zP3FxdDlcSQGC1qvM9lHZRaHH4I9Jwwa) (Google Drive)
+  - [How we use RFCs](../communication/rfcs/index.md)
+- [Tracking issues](tracking_issues.md)
+- Practices & Philosophy
+  - [Customer Issues](../support/engaging-other-teams.md)
+  - [Incidents](incidents/index.md)
+  - [Product documentation](product_documentation.md)
+  - [Continuous releasability](continuous_releasability.md)
+  - [Releases](releases/index.md)
+    - [Release issue template](releases/release_issue_template.md)
+  - [External contributions](external_contributions.md)
+  - Guides on development, local setup, testing, best practices, etc. can be found in our "[Developing Sourcegraph](https://docs.sourcegraph.com/dev)" documentation.
+- Tooling
+  - [Configuring Zoom to send recordings to Slack automatically](configuring_zoom_recordings_to_slack_automatically.md)
+- Infrastructure
+  - [Cloud environments](environments.md)
+  - [Deployments](deployments/index.md)
+  - [On-call](incidents/on_call.md)
+  - [Observability](observability/index.md)
+
+## Org chart
+
+- [How engineering is organized](eng_org.md).
+- [Roles and responsibilities](roles.md)
+
+
+## Communication
+
+For a list of engineering relevant Slack channels to join see the [team chat](../communication/team_chat.md#engineering) page in the handbook.
+
+## Open positions
+
+[Open positions](hiring/index.md#open-positions)
+
+
+## Repositories
+
+Sourcegraph has a lot of repositories!
+
+## Where Sourcegraph is built (things you'll find out-of-the-box):
+
+- [Main repositories](https://github.com/sourcegraph?utf8=%E2%9C%93&q=repo-type-main&type=&language=)
+- [Web development repositories](https://github.com/sourcegraph?utf8=%E2%9C%93&q=repo-type-web&type=&language=)
+- [Backend repositories](https://github.com/sourcegraph?utf8=%E2%9C%93&q=repo-type-backend&type=&language=)
+- [Tooling repositories](https://github.com/sourcegraph?utf8=%E2%9C%93&q=repo-type-tooling&type=&language=)
+- [Documentation repositories](https://github.com/sourcegraph?utf8=%E2%9C%93&q=repo-type-docs&type=&language=)
+
+## How Sourcegraph gets deployed:
+
+- [Infrastructure repositories](https://github.com/sourcegraph?utf8=%E2%9C%93&q=repo-type-infrastructure&type=&language=)
+- [Customer infrastructure repositories](https://github.com/sourcegraph?utf8=%E2%9C%93&q=repo-type-infrastructure+repo-type-customer&type=&language=)
+
+## Sourcegraph deployments and other developer test instances:
+
+- [sourcegraph.com](https://sourcegraph.com) is our production deployment for open source code.
+- [sourcegraph.sgdev.org](http://sourcegraph.sgdev.org) is our private deployment of Sourcegraph that contains some of our private code.
+- [k8s.sgdev.org](https://k8s.sgdev.org) is a dogfood deployment that replicates the scale of our largest customers.
+- [demo.sourcegraph.com](https://demo.sourcegraph.com) is a managed instance used for CE demos.
+- [devmanaged.sourcegraph.com](https://devmanaged.sourcegraph.com) is a managed instance used for managed instances development.
+- [storybook.sgdev.org](http://storybook.sgdev.org) is a design system built with Storybook.
+- [gerrit.sgdev.org](https://gerrit.sgdev.org) is a Gerrit test instance.
+- [gitlab.sgdev.org](https://gitlab.sgdev.org) is a Gitlab test instance.
+- [github.sgdev.org](https://github.sgdev.org) is a Github test instance.
+- [bitbucket.sgdev.org](https://bitbucket.sgdev.org) is a Bitbucket test instance.
+
+## Where Sourcegraph gets extended functionality:
+
+- [Code intelligence repositories](https://github.com/sourcegraph?utf8=%E2%9C%93&q=repo-type-codeintel&type=&language=)
+- [CLI repositories](https://github.com/sourcegraph?utf8=%E2%9C%93&q=repo-type-cli&type=&language=)
+- [Editor extension repositories](https://github.com/sourcegraph?utf8=%E2%9C%93&q=repo-type-editor&type=&language=)
+
+## How Sourcegraph operates as a business
+
+- [Business repositories](https://github.com/sourcegraph?utf8=%E2%9C%93&q=repo-type-business&type=&language=)
+- [Customer repositories](https://github.com/sourcegraph?utf8=%E2%9C%93&q=repo-type-customer&type=&language=)
+
+## Misc.
+
+This point lives here for now:
+
+- We require passing checks on GitHub PRs before merging (and don't allow direct pushes to master). Sometimes it's nice to push without waiting for checks (such as for docs-only changes), but this is outweighed by the downside that people too often accidentally merged changes that broke the build. Certain kinds of low risk changes (e.g., documentation only changes) may only run a subset of the build pipeline so that checks pass quickly in those cases.
+

handbook-new/content/handbook/editing.mdx

@@ -0,0 +1,150 @@
+---
+title: "How to edit the Sourcegraph handbook"
+description: "Instructions for how to edit the content of the Sourcegraph handbook"
+---
+
+# Editing the handbook
+
+Every Sourcegraph teammate will be editing the Sourcegraph handbook frequently to keep information up-to-date and participate in important changes in the company. This guide helps everyone learn how to edit the handbook.
+
+The handbook consists of Markdown files in the Git repository at [github.com/sourcegraph/about](https://github.com/sourcegraph/about). ([Why not a wiki or Google Docs?](usage.md#wiki-and-google-docs-handbooks-become-stale))
+
+## How to get help
+
+We don't expect everyone on the team to figure this out on their own. Other teammates are happy to help!
+
+- Any engineer at Sourcegraph can help. (The *code* that engineers write at Sourcegraph also consists of files in a Git repository, so engineers are very familiar with making these kinds of edits.)
+- [Teammates who have already made a handbook change](https://sourcegraph.com/github.com/sourcegraph/about/-/stats/contributors?path=handbook%2F) can help.
+- **Handbook support**: Ask the @handbook-support group in Slack (including @eric, @aharvey, @virginia, and @jean) for handbook help (via DM, #handbook, or #any-question). They volunteered to help anyone with anything handbook-related! _If you too want to be part of handbook support, simply edit this page, add your name to the list and ping @handbook-support in the #handbook channel to inform them_
+- Ask in #handbook: `Who can screen-share with me to help me make an edit to the handbook?`
+- Don't be afraid of breaking anything! It is very easy for any engineer on the team to roll back to the previous version of the handbook if you make a mistake.
+
+## Overview
+
+Here's the process for getting a change published to the handbook. For detailed step-by-step instructions (intended for people who are new to Git), see the sections below.
+
+1. Propose the edits you want to make by creating a [pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) on the Git repository at [github.com/sourcegraph/about](https://github.com/sourcegraph/about).
+   - Because the [handbook is public](usage.md#why-make-this-handbook-public), anyone in the world can see your proposed edits.
+1. You can request a review from specific teammates (who will get a notification) on the GitHub pull request page.
+   - We don't have any rules around who needs to review what changes. Use your judgment (e.g., if your change affects the entire engineering team, request review from the VP Engineering).
+   - For minor edits, you can skip review.
+1. Wait for the necessary teammates to review and approve your pull request.
+1. Merge the pull request.
+1. Wait up to 5 minutes for your change to be live on about.sourcegraph.com.
+1. Use the #handbook-announce label to notify other people of important handbook updates on the #handbook-announce Slack channel.
+
+## Reviewing and approving another person's proposal
+
+Frequently used links:
+
+- [All proposed (and not yet merged) handbook changes](https://github.com/sourcegraph/about/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc)
+- [Proposed handbook changes waiting on review by you](https://github.com/sourcegraph/about/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+review-requested%3A%40me)
+- [Proposed handbook changes submitted by you](https://github.com/sourcegraph/about/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+author%3A%40me)
+
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/Q8tUXKU66Sk" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+## Edit a single file
+
+If you just need to edit a single page, you can do it entirely on the web.
+
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/MsIGvw0IEzo" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+<br/>
+
+1. Visit the handbook page you want to edit on about.sourcegraph.com.
+1. Press the **Edit this page** button in the sidebar.
+   - If you don't see it, you may be viewing a page on about.sourcegraph.com that is not part of the handbook. Handbook pages all have the same design as the [main handbook page](https://about.sourcegraph.com/handbook). If it has a different design, [ask for help](#how-to-get-help).
+1. In the text editor, make your edits.
+   - The document is in a format called Markdown that lets you use headings, links, bold, lists, etc., in a plain text file. See "[Mastering Markdown](https://guides.github.com/features/mastering-markdown/)" and feel free to [ask for help](#how-to-get-help).
+1. Switch back and forth to the **Preview changes** tab at the top of the editor to see the nicely rendered page with your edits applied.
+   - Deletions are shown in red, changes are shown in orange, and additions are shown in green.
+1. When you're happy with your edits, scroll to the bottom of the page to the **Commit changes** box.
+   - Type a short, one-line summary of your change in the first text field (instead of the default `Update filename.md` text).
+   - Type a more detailed explanation of your change in the larger text field.
+   - Select the **Create a new branch for this commit and start a pull request** option (if it's not already selected).
+   - Press the **Commit changes** button.
+1. Press the **Create pull request** button. Now your change has been proposed!
+   - You can share the link to the pull request with anyone to show them your proposed change (e.g., `https://github.com/sourcegraph/about/pull/123).
+1. If you want this update to be published in the Slack channel #handbook-announce, select the handbook-announce label using the **Label** button on the right side of the pull request page.
+1. Select teammates to review using the **Reviewers** button on the right side of the pull request page.
+1. Wait for teammates to review, comment on, and approve your pull request.
+1. When you're ready to publish the change and make it live, press the **Squash and merge** button, then press **Confirm squash and merge**.
+1. Wait up to 5 minutes for your change to be live on about.sourcegraph.com.
+
+## Edit multiple files or add a new file
+
+To make edits to multiple files and submit all of the edits as a group to be reviewed together, you will follow a more complex process than when [editing a single file](#edit-a-single-file). This also is required for adding new files.
+
+> NOTE: These steps are not exhaustively documented. Please [ask for help](#how-to-get-help) as many times as you need to until you feel comfortable with this process.
+
+### Web interface
+
+#### Multiple changes in a single PR
+
+A screen recording of how to make multiple changes in a single PR in the web interface for GitHub:
+
+<iframe src="https://drive.google.com/file/d/1UL3JqbXEGLaVXEkk4G81wGO69z8J_Cbw/preview" width="560" height="315"></iframe>
+
+#### Making a new page
+
+A screen recording of how to make a new file and include it for review in the web interface for GitHub:
+
+<iframe src="https://drive.google.com/file/d/16iYS-idCL5FEGwoldF7rOQElcidgzo8i/preview" width="560" height="315"></iframe>
+
+### macOS
+
+### Github Desktop version
+Here's a screen recording of the steps (written out below) for macOS:
+
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/diZUeHZhekc" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+#### Prerequisites
+
+1. Download and install [GitHub Desktop](https://desktop.github.com/).
+1. Launch GitHub Desktop and sign into it using your GitHub username.
+1. Clone the `sourcegraph/about` repository (assuming to the `~/Documents/GitHub/about` folder on your computer).
+
+Optional:
+
+- Use [Typora](https://www.typora.io/) to edit and preview Markdown (`.md`) files.
+
+#### Steps
+
+1. In GitHub Desktop, open the `about` repository that you cloned previously.
+1. In **Current Branch**, select `main` if it's not already selected.
+1. Press the **Fetch Origin** button to get the latest contents of the repository.
+1. In **Current Branch**, create a new branch with a short name (like `add-travel-guidelines`, no spaces or punctuation).
+1. Edit files in the `~/Documents/GitHub/about/handbook` folder on your computer.
+1. When you've edited the files and saved your changes, GitHub Desktop will show you the changed files in the left sidebar. Confirm that your changes look good by viewing the diffs for each file.
+1. In the bottom left `Summary (required)` text field, type your commit message (a one-line description of the change) and a longer `Description` below.
+1. Press the **Commit to add-travel-guidelines** button (where `add-travel-guidelines` is the branch name you chose earlier).
+1. Press the **Publish branch** button.
+1. Press the **Create Pull Request** button.
+1. On the pull request page in your web browser, select reviewers and wait for reviews/approvals, then merge to make the changes live.
+
+## Adding images
+
+Pictures, images, and graphics must be uploaded to Google Cloud Storage to be added to a handbook or documentation page. See the [Technical Writing page](product/technical_writing/index.md#uploading-graphics) for instructions.
+
+## Uploading large files
+
+If you want to upload a large file (such as a large image, video, or audio recording) and make it available in the handbook, upload the file to Google Drive and then get a shareable link to the file on Google Drive. Add that link to the handbook. Don't add large files to the handbook repository itself (because Git is not a good way to store large non-text files).
+
+## Adding redirects
+
+When you change the location of content in the handbook it's important to add a redirect rule so that old URL to the content will automatically take users to the new URL.
+
+To add a redirect rule edit edit the following file: `/_resources/assets/redirects`
+
+Redirect rules follows a simply syntax of: `from-path to-path 308`
+E.g. `/handbook/ce/support/ /handbook/support/ 308`
+
+## Running a local preview handbook site
+
+> NOTE: This is optional.
+
+See the [handbook section](https://github.com/sourcegraph/about#handbook) in the repository README.
+
+## Handbook feedback
+
+We're constantly iterating on what the best version of our Sourcegraph handbook might look like. Is it easy to use? Do you find what you're looking for? Let us know [here](https://docs.google.com/forms/d/e/1FAIpQLSfb0yU9xmnvK2namuUzUEKbB9IqZlNQF2IWw0OpLsGvBiW2oQ/viewform?usp=sf_link).

handbook-new/content/handbook/index.mdx

@@ -0,0 +1,12 @@
+---
+title: "Sourcegraph handbook"
+description: ""
+---
+
+The Sourcegraph handbook describes how we (Sourcegraph teammates) work. It’s publicly visible because we are an open company.
+
+The handbook is a living document and we expect every teammate to propose improvements, changes, additions, and fixes to keep it continuously up-to-date and accurate.
+
+- [Editing the handbook](/handbook/editing)
+- [Handbook usage](/handbook/usage)
+- [Handbook feedback](https://docs.google.com/forms/d/e/1FAIpQLSfb0yU9xmnvK2namuUzUEKbB9IqZlNQF2IWw0OpLsGvBiW2oQ/viewform?usp=sf_link)