Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reformat MD files to limit line lengths to 80 characters #4540

Merged
merged 8 commits into from
Aug 6, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/markdownlint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ jobs:
steps:
- uses: actions/checkout@v2
- name: Use Node.js
uses: actions/setup-node@v1
uses: actions/setup-node@v4
with:
node-version: lts/*
- name: Run Markdownlint
Expand Down
6 changes: 5 additions & 1 deletion .markdownlint.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
{
"default": true,
"MD013": false, // 80 char line length
// line length
"MD013": {
"code_block_line_length": 256,
"heading_line_length": 96
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

},
"MD033": false, // no inline HTML
}
3 changes: 2 additions & 1 deletion CODE-OF-CONDUCT.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,5 @@
This project has adopted the code of conduct defined by the Contributor Covenant
to clarify expected behavior in our community.

For more information, see the [.NET Foundation Code of Conduct](https://dotnetfoundation.org/code-of-conduct).
For more information, see the [.NET Foundation Code of
Conduct](https://dotnetfoundation.org/code-of-conduct).
107 changes: 64 additions & 43 deletions Documentation/VMR-re-bootstrapping.md
Original file line number Diff line number Diff line change
@@ -1,79 +1,100 @@
# How to re-bootstrap the toolset used to build the VMR

.NET utilizes itself to build. Therefore, in order to build .NET from source, you
first need to acquire or build a bootstrapping .NET SDK and other tooling such
as [Arcade](https://github.com/dotnet/arcade). Re-bootstrapping is the term used to describe when the bootstrapped
toolset need to be updated. This document describes the steps to re-bootstrap
the VMR.
.NET utilizes itself to build. Therefore, in order to build .NET from source,
you first need to acquire or build a bootstrapping .NET SDK and other tooling
such as [Arcade](https://github.com/dotnet/arcade). Re-bootstrapping is the term
used to describe when the bootstrapped toolset need to be updated. This document
describes the steps to re-bootstrap the VMR.

## When is it appropriate to re-bootstrap?

As part of the release process, the toolset is updated (e.g. PRs are created via
the release automation). Outside of a release, re-bootstrapping is only permitted
during preview releases. It is not allowed during RC, GA, or servicing releases.
The reason it is not allowed during non-preview releases is because of the negative
impact it has on Linux distro maintainers who source build .NET. It is often a long
and time consuming process for them to re-bootstrap. It is likely to cause
significant delays in the release/availability of .NET within the distros that are
source built.
the release automation). Outside of a release, re-bootstrapping is only
permitted during preview releases. It is not allowed during RC, GA, or servicing
releases. The reason it is not allowed during non-preview releases is because of
the negative impact it has on Linux distro maintainers who source build .NET. It
is often a long and time consuming process for them to re-bootstrap. It is
likely to cause significant delays in the release/availability of .NET within
the distros that are source built.

## Why is re-bootstrap necessary?

Re-bootstrapping is necessary when .NET takes a dependency on new functionality
added within the bootstrap toolset. For example suppose a new compiler feature is
added. In order for a repo to take a dependency on the new feature, a re-bootstrap
would be necessary. The implication of this, and the restrictions of when
re-bootstrapping is allowed, means that repos should, in general, wait to take a
dependency on a new toolset feature until after that feature has been released.
added within the bootstrap toolset. For example suppose a new compiler feature
is added. In order for a repo to take a dependency on the new feature, a
re-bootstrap would be necessary. The implication of this, and the restrictions
of when re-bootstrapping is allowed, means that repos should, in general, wait
to take a dependency on a new toolset feature until after that feature has been
released.

## Steps to re-bootstrap

### Automated

> [!IMPORTANT]
> The re-bootstrap pipeline uploads the artifacts to the official blob storage,
> so do not use this pipeline for testing of any kind.
> To test stage 2 failures, please refer to [this documentation](bootstrapping-guidelines.md#building-on-a-supported-platform-using-rid-known-to-net).
> so do not use this pipeline for testing of any kind. To test stage 2 failures,
> please refer to [this
> documentation](bootstrapping-guidelines.md#building-on-a-supported-platform-using-rid-known-to-net).

You can re-bootstrap the VMR using [this pipeline](https://dev.azure.com/dnceng/internal/_build?definitionId=1371).
The pipeline will upload the artifacts & open the corresponding re-bootstrap PR.
You can re-bootstrap the VMR using [this
pipeline](https://dev.azure.com/dnceng/internal/_build?definitionId=1371). The
pipeline will upload the artifacts & open the corresponding re-bootstrap PR.

### Manual

In case the automated re-bootstrapping pipeline is unavailable, you can manually re-bootstrap the VMR:
In case the automated re-bootstrapping pipeline is unavailable, you can manually
re-bootstrap the VMR:

1. Update previous source-build artifacts
1. Find a [dotnet-source-build](https://dev.azure.com/dnceng/internal/_build?definitionId=1219) run
with the desired changes.
1. If a rebootstrap is needed quickly and it is not feasibly to wait for a
[dotnet-source-build](https://dev.azure.com/dnceng/internal/_build?definitionId=1219) run,
you can also use the artifacts from a
[dotnet-source-build-lite](https://dev.azure.com/dnceng/internal/_build?definitionId=1299) run.
1. Retrieve the built SDKs and private source-built artifacts archives, from the following legs:
1. Find a
[dotnet-source-build](https://dev.azure.com/dnceng/internal/_build?definitionId=1219)
run with the desired changes.
1. If a rebootstrap is needed quickly and it is not feasibly to wait for
a
[dotnet-source-build](https://dev.azure.com/dnceng/internal/_build?definitionId=1219)
run, you can also use the artifacts from a
[dotnet-source-build-lite](https://dev.azure.com/dnceng/internal/_build?definitionId=1299)
run.
1. Retrieve the built SDKs and private source-built artifacts archives, from
the following legs:
1. Alpine\<nnn\>_Online_MsftSdk_x64
1. CentOSStream\<n\>_Online_MsftSdk_x64
1. Upload the SDKs to the [source build sdk blob storage](https://dotnetcli.blob.core.windows.net/source-built-artifacts/sdks/)
1. Upload the private source-built artifacts archives to the [source build assets blob storage](https://dotnetcli.blob.core.windows.net/source-built-artifacts/assets/)
1. Upload the SDKs to the [source build sdk blob
storage](https://dotnetcli.blob.core.windows.net/source-built-artifacts/sdks/)
1. Upload the private source-built artifacts archives to the [source build
assets blob
storage](https://dotnetcli.blob.core.windows.net/source-built-artifacts/assets/)
1. Update .NET SDK
1. Find the [dotnet-sdk-official-ci](https://dev.azure.com/dnceng/internal/_build?definitionId=140) build
that best matches the dotnet-source-build. The following is the suggested
order of precedence for finding the best match.
1. Find the
[dotnet-sdk-official-ci](https://dev.azure.com/dnceng/internal/_build?definitionId=140)
build that best matches the dotnet-source-build. The following is the
suggested order of precedence for finding the best match.
1. A build from the same commit.
1. From the [dotnet-source-build](https://dev.azure.com/dnceng/internal/_build?definitionId=1219),
1. From the
[dotnet-source-build](https://dev.azure.com/dnceng/internal/_build?definitionId=1219),
look at the build's installer tag.
1. From a VMR commit, you can find the corresponding installer commit
by looking at the [source-manifest.json](https://github.com/dotnet/dotnet/blob/main/src/source-manifest.json).
1. From a VMR commit, you can find the corresponding installer
commit by looking at the
[source-manifest.json](https://github.com/dotnet/dotnet/blob/main/src/source-manifest.json).
1. The next passing build after the same commit.
1. In the odd case where the are no passing builds after the commit, you
can try using an earlier passing build.
1. Retrieve the built SDK version from the build.
1. Update the dotnet version in the [global.json](https://github.com/dotnet/installer/blob/main/src/SourceBuild/content/global.json).
1. Update the dotnet version in the
[global.json](https://github.com/dotnet/installer/blob/main/src/SourceBuild/content/global.json).
1. Update arcade
1. Lookup the arcade commit and version. From a VMR commit, you can find the
corresponding arcade commit/version by looking at the [source-manifest.json](https://github.com/dotnet/dotnet/blob/main/src/source-manifest.json).
1. Update the arcade SDK version in the [global.json](https://github.com/dotnet/installer/blob/main/src/SourceBuild/content/global.json).
1. Update the arcade dependency commit and version in the [Version.Details.xml](https://github.com/dotnet/installer/blob/main/src/SourceBuild/content/eng/Version.Details.xml).
corresponding arcade commit/version by looking at the
[source-manifest.json](https://github.com/dotnet/dotnet/blob/main/src/source-manifest.json).
1. Update the arcade SDK version in the
[global.json](https://github.com/dotnet/installer/blob/main/src/SourceBuild/content/global.json).
1. Update the arcade dependency commit and version in the
[Version.Details.xml](https://github.com/dotnet/installer/blob/main/src/SourceBuild/content/eng/Version.Details.xml).
1. Update private source-built SDK and artifacts versions
1. Update `PrivateSourceBuiltSdkVersion` and `PrivateSourceBuiltArtifactsVersion` in the [Versions.props](https://github.com/dotnet/installer/blob/main/src/SourceBuild/content/eng/Versions.props).
1. Update `PrivateSourceBuiltSdkVersion` and
`PrivateSourceBuiltArtifactsVersion` in the
[Versions.props](https://github.com/dotnet/installer/blob/main/src/SourceBuild/content/eng/Versions.props).

[Tracking issue for automating this process.](https://github.com/dotnet/source-build/issues/4246)
[Tracking issue for automating this
process.](https://github.com/dotnet/source-build/issues/4246)
Loading
Loading