Skip to content

Commit 5fae4d6

Browse files
authored
Added instructions to the documentation for forking the main repo. (#33098)
* Added instructions to the documentation for forking the main repo. * Added a link to basic GitHub flow for forking repos. * Fixed a broken section link. * Added additional information and link for fetching upstream changes.
1 parent 1545d7b commit 5fae4d6

File tree

1 file changed

+41
-6
lines changed

1 file changed

+41
-6
lines changed

docs/BuildFromSource.md

+41-6
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Build ASP.NET Core from Source
22

3-
This document outlines how to build the source in the aspnetcore repo locally for development purposes.
3+
This document outlines how to build the source in the `aspnetcore` repo locally for development purposes.
44

55
For more info on issues related to build infrastructure and ongoing work, see <https://github.com/dotnet/aspnetcore/labels/area-infrastructure>.
66

@@ -9,27 +9,62 @@ For more info on issues related to build infrastructure and ongoing work, see <h
99
This tutorial assumes that you are familiar with:
1010

1111
- Git
12+
- The basics of [forking and contributing to GitHub projects](https://guides.github.com/activities/forking/)
1213
- Command line fundamentals in your operating system of choice
1314

14-
## Step 1: Clone the source code
15+
## Step 1: Getting the source code
16+
17+
Development is done in your own repo, not directly against the official `dotnet/aspnetcore` repo. To create your own fork, click the __Fork__ button from our GitHub repo as a signed-in user and your own fork will be created.
18+
19+
> :bulb: All other steps below will be against your fork of the aspnetcore repo (e.g. `YOUR_USERNAME/aspnetcore`), not the official `dotnet/aspnetcore` repo.
20+
21+
### Cloning your repo locally
1522

1623
ASP.NET Core uses git submodules to include the source from a few other projects. In order to pull the sources of the these submodules when cloning the repo, be sure to pass the `--recursive` flag to the `git clone` command.
1724

1825
```powershell
19-
git clone --recursive https://github.com/dotnet/aspnetcore
26+
git clone --recursive https://github.com/YOUR_USERNAME/aspnetcore
2027
```
2128

22-
If you've already cloned the aspnetcore repo without fetching submodule sources, you can fetch them after cloning by running the following command.
29+
If you've already cloned the `aspnetcore` repo without fetching submodule sources, you can fetch them after cloning by running the following command.
2330

2431
```powershell
2532
git submodule update --init --recursive
2633
```
2734

2835
> :bulb: Some ISPs have been know to use web filtering software that has caused issues with git repository cloning, if you experience issues cloning this repo please review <https://help.github.com/en/github/authenticating-to-github/using-ssh-over-the-https-port>.
2936
37+
### Tracking remote changes
38+
39+
The first time you clone your repo locally, you'll want to set an additional Git remote back to the official repo so that you can periodically refresh your repo with the latest official changes.
40+
41+
```powershell
42+
git remote add upstream https://github.com/dotnet/aspnetcore.git
43+
```
44+
45+
You can verify the `upstream` remote has been set correctly.
46+
47+
```powershell
48+
git remote -v
49+
> origin https://github.com/YOUR_USERNAME/aspnetcore (fetch)
50+
> origin https://github.com/YOUR_USERNAME/aspnetcore (push)
51+
> upstream https://github.com/dotnet/aspnetcore.git (fetch)
52+
> upstream https://github.com/dotnet/aspnetcore.git (push)
53+
```
54+
55+
Once configured, the easiest way to keep your repository current with the upstream repository is using GitHub's feature to [fetch upstream changes](https://github.blog/changelog/2021-05-06-sync-an-out-of-date-branch-of-a-fork-from-the-web/).
56+
57+
### Branching
58+
59+
If you ultimately want to be able to submit a PR back to the project or be able to periodically refresh your `main` branch with the latest code changes, you'll want to do all your work on a new branch.
60+
61+
```powershell
62+
git checkout -b NEW_BRANCH
63+
```
64+
3065
## Step 2: Install pre-requisites
3166

32-
Developing in the aspnetcore repo requires some additional tools to build the source code and run integration tests.
67+
Developing in the `aspnetcore` repo requires some additional tools to build the source code and run integration tests.
3368

3469
### On Windows
3570

@@ -234,7 +269,7 @@ code .
234269
235270
### Building on command-line
236271

237-
When developing in VS Code, you'll need to use the `build.cmd` or `build.sh` scripts in order to build the project. You can learn more about the command line options available, check out [the section below](using-dotnet-on-command-line-in-this-repo).
272+
When developing in VS Code, you'll need to use the `build.cmd` or `build.sh` scripts in order to build the project. You can learn more about the command line options available, check out [the section below](#using-dotnet-on-command-line-in-this-repo).
238273

239274
> :warning: Most of the time, you will want to build a particular project instead of the entire repository. It's faster and will allow you to focus on a particular area of concern. If you need to build all code in the repo for any reason, you can use the top-level build script located under `eng\build.cmd` or `eng\build.sh`.
240275

0 commit comments

Comments
 (0)