Skip to content

Commit

Permalink
use GitHub for all github.coms and add an associated phrasing contrib…
Browse files Browse the repository at this point in the history
…uting section
  • Loading branch information
sjspielman committed Mar 12, 2024
1 parent ea38887 commit 7386692
Show file tree
Hide file tree
Showing 4 changed files with 22 additions and 14 deletions.
8 changes: 8 additions & 0 deletions docs/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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`
12 changes: 6 additions & 6 deletions docs/technical-setup/clone-the-repo.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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.
Expand All @@ -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"} <!-- No new line above, to keep tabbed in -->

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"} <!-- No new line above, to keep tabbed in -->

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"} <!-- No new line above, to keep tabbed in. Width needs to be >=325 for proper spacing, it seems. -->
8 changes: 4 additions & 4 deletions docs/technical-setup/fork-the-repo.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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"} <!-- No new line above, to keep tabbed in -->
![Button on `GitHub` to fork a repository.](../img/fork-button.png){width="400"} <!-- No new line above, to keep tabbed in -->


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`.
Expand All @@ -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).
8 changes: 4 additions & 4 deletions docs/technical-setup/install-a-github-client.md
Original file line number Diff line number Diff line change
@@ -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).

Expand All @@ -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?
Expand All @@ -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
Expand Down

0 comments on commit 7386692

Please sign in to comment.