From 73866927509f9c3d9abd7946bcb39171f5c04b1c Mon Sep 17 00:00:00 2001 From: "Stephanie J. Spielman" Date: Tue, 12 Mar 2024 11:51:22 -0400 Subject: [PATCH] use GitHub for all github.coms and add an associated phrasing contributing section --- docs/contributing.md | 8 ++++++++ docs/technical-setup/clone-the-repo.md | 12 ++++++------ docs/technical-setup/fork-the-repo.md | 8 ++++---- docs/technical-setup/install-a-github-client.md | 8 ++++---- 4 files changed, 22 insertions(+), 14 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 48404e7ca..2b4bb4ce7 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -19,6 +19,7 @@ To serve the documentation during local development, run `mkdocs serve` from the - [Docs organization](#docs-organization) - [Adding new documentation](#adding-new-documentation) - [Linking to other pages](#linking-to-other-pages) +- [Phrasing](#phrasing) ## Docs organization @@ -85,3 +86,10 @@ For example: ``` This sentence should link to the [pull request documentation](STUB_LINK). ``` + + +## Phrasing + +For consistency, please use the following: + +- Refer to github.com as `GitHub` diff --git a/docs/technical-setup/clone-the-repo.md b/docs/technical-setup/clone-the-repo.md index ebe43a849..63d62b53e 100644 --- a/docs/technical-setup/clone-the-repo.md +++ b/docs/technical-setup/clone-the-repo.md @@ -12,7 +12,7 @@ You will need to clone the repository to every computer (or remote server) you w Please follow the [instructions in this GitKraken video](https://help.gitkraken.com/gitkraken-client/open-clone-init/#cloning-an-existing-project) to clone your repository. -This video presents two approaches to cloning: `Clone with URL`, and Clone based on your integrated `GitHub.com` account. +This video presents two approaches to cloning: `Clone with URL`, and Clone based on your integrated `GitHub` account. Either approach is fine to take! While watching these instructions, please bear in mind the following: @@ -25,11 +25,11 @@ This does not apply to `OpenScPCA-analysis`. ## Add the project repository as a remote repository The next step is to link the upstream repository (`AlexsLemonade/OpenScPCA-analysis`) as a remote. -A _remote_ is a repository on GitHub.com that you are connected to. +A _remote_ is a repository on `GitHub` that you are connected to. Each remote repository is given a name to make referring to them easier. -For example, your forked repository on GitHub.com is called `origin` because it is where your local repository was cloned from. +For example, your forked repository on `GitHub` is called `origin` because it is where your local repository was cloned from. -We will add another remote repository named `upstream` that refers to the original `AlexsLemonade/OpenScPCA-analysis` repository on GitHub.com. +We will add another remote repository named `upstream` that refers to the original `AlexsLemonade/OpenScPCA-analysis` repository on `GitHub`. This will be called `upstream` because it was the source that your fork came from. Adding the `AlexsLemonade` _upstream remote_ will allow you to interact with it from your computer which can help you keep your fork in sync with the `OpenScPCA` project. @@ -42,11 +42,11 @@ This text will then turn into a plus-sign icon. Click that icon. ![Click button to add the remote.](../img/add-upstream-remote-1.png){width="600"} -2. The following screen will prompt you to add a remote. +1. The following screen will prompt you to add a remote. Select `AlexsLemonade/OpenScPCA-analysis` from the dropdown menu, and click the button `Add remote`. ![Add the upstream remote.](../img/add-upstream-remote-2.png){width="400"} -3. You should then see a second remote called `AlexsLemonade` on the left-hand side `Remote` panel. +1. You should then see a second remote called `AlexsLemonade` on the left-hand side `Remote` panel. The specific listed items under this remote that you see will look different from the screenshot below; this is expected. As long as you see that `AlexsLemonade` is listed in the menu, you have successfully added the upstream remote. ![View the added remote.](../img/add-upstream-remote-3.png){width="325"} diff --git a/docs/technical-setup/fork-the-repo.md b/docs/technical-setup/fork-the-repo.md index 021794bf4..32c17f5b2 100644 --- a/docs/technical-setup/fork-the-repo.md +++ b/docs/technical-setup/fork-the-repo.md @@ -2,7 +2,7 @@ You will need to create a [_fork_](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#about-forks) of the [`OpenScPCA-analysis`](https://github.com/AlexsLemonade/OpenScPCA-analysis/) repository. -A fork is a copy of an _upstream_ repository (here, `AlexsLemonade/OpenScPCA-analysis` is the _upstream_) that you will own and will be in your GitHub account. +A fork is a copy of an _upstream_ repository (here, `AlexsLemonade/OpenScPCA-analysis` is the _upstream_) that you will own and will be in your `GitHub` account. As a contributor, you will perform analyses in your fork. Just like the upstream `AlexsLemonade/OpenScPCA-analysis` repository, your fork will also be a public repository. @@ -20,10 +20,10 @@ Follow these steps to create your fork: 1. At the top right corner, click the "Fork" button: (The numbers you see in this screenshot may differ from the numbers on the website - that's ok!) -![Button on GitHub.com to fork a repository.](../img/fork-button.png){width="400"} +![Button on `GitHub` to fork a repository.](../img/fork-button.png){width="400"} -1. On the next screen, GitHub will prompt you for some settings about your fork. +1. On the next screen, `GitHub` will prompt you for some settings about your fork. Make sure that these conditions are met, and then click the "Create fork" button on the bottom right. - Although the screenshot below shows an "Owner" username of `sjspielman`, you should see your username in this field. - Keep the default Repository name as `OpenScPCA-analysis`. @@ -33,4 +33,4 @@ Make sure that these conditions are met, and then click the "Create fork" button 1. That's it! 🎉 -In a few moments, GitHub will redirect to your newly forked repository at `https://github.com/YOUR_USERNAME/OpenScPCA-analysis`, and you're ready to proceed to the next step of [cloning your repository](./clone-the-repo.md). +In a few moments, `GitHub` will redirect to your newly forked repository at `https://github.com/YOUR_USERNAME/OpenScPCA-analysis`, and you're ready to proceed to the next step of [cloning your repository](./clone-the-repo.md). diff --git a/docs/technical-setup/install-a-github-client.md b/docs/technical-setup/install-a-github-client.md index cbed1776d..9a0e23a2e 100644 --- a/docs/technical-setup/install-a-github-client.md +++ b/docs/technical-setup/install-a-github-client.md @@ -1,6 +1,6 @@ # Install a GitHub client -You will need a platform on your computer to run Git commands and interact with [GitHub.com](https://github.com). +You will need a platform on your computer to run Git commands and interact with [GitHub.com](https://github.com) (`GitHub`). There are many platforms you can choose, but we recommend using either [**GitKraken**](https://www.gitkraken.com/) or the [Git **command line interface**](https://git-scm.com/book/en/v2/Getting-Started-The-Command-Line). @@ -19,8 +19,8 @@ GitKraken is free to use with public repositories like `OpenScPCA-analysis`; you 1. Install GitKraken [using this link](https://www.gitkraken.com/download). -2. Set up GitKraken on your machine by [directly signing in with your GitHub account](https://help.gitkraken.com/gitkraken-client/github-gitkraken-client/#sign-in-with-github). -This will automatically provide you with the credentials you need to interact with GitHub without further setup. +2. Set up GitKraken on your machine by [directly signing in with your `GitHub` account](https://help.gitkraken.com/gitkraken-client/github-gitkraken-client/#sign-in-with-github). +This will automatically provide you with the credentials you need to interact with `GitHub` without further setup. ## Why use the Git command line interface? @@ -38,7 +38,7 @@ The instructions for this depend on your operating system, as described below. After installing Git, you will also need take these steps: -- [Set up an SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) to interact with GitHub +- [Set up an SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) to interact with `GitHub` - [Set up your Git config file](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup) ### Install Git on MacOS