Skip to content

Commit 7aef237

Browse files
committed
Update documentation.
Fix references to old versions of tools. Fix stop specifying specific python version, reference version from mu_devops. Add page for cherry-pick process into mu repos. Update example rust to latest rust version, while still referencing the rust-toolchain.toml files for specific version.
1 parent 067a652 commit 7aef237

7 files changed

Lines changed: 92 additions & 23 deletions

File tree

docs/CodeDevelopment/compile.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,8 +63,8 @@ the Pull Requests gates are implemented and enforced.
6363
6464
???+ info
6565
- In Project Mu repos the config file is generally at ```.pytool/CISettings.py```
66-
- Project Mu runs on Windows 10 using the following tags: VS2019 and VS2022
67-
- Project Mu runs on Ubuntu 18.04 using the tags: GCC5
66+
- Project Mu runs on Windows 11 using the following tags: VS2019 and VS2022
67+
- Project Mu runs on Ubuntu 24.04 using the tags: GCC5
6868
- Each of the stuart commands can take in additional parameters. To see customized help run
6969
`<stuart cmd> -c .pytool/CISettings.py -h`
7070
- Some common optional parameters that *might* allow the stuart operation to optimize for expected usage.

docs/CodeDevelopment/prerequisites.md

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,11 @@ get you started. If the repo requires other tools those should be documented wi
66
The tools also vary by Operating System and Compiler choice. Project Mu will document what is currently supported but
77
the expectation is that between Project Mu and TianoCore Edk2 you could use any of those tool sets.
88

9-
## Windows 10 x64
9+
## Windows 11 x64
1010

1111
### Python
1212

13-
1. Download latest Python from <https://www.python.org/downloads>
14-
15-
``` cmd
16-
https://www.python.org/ftp/python/3.10.7/python-3.10.7-amd64.exe
17-
```
18-
13+
1. Install python. Recommended version can be viewed on [mu_devops](https://github.com/microsoft/mu_devops/blob/main/.sync/Version.njk).
1914
2. It is recommended you use the following options when installing python:
2015
1. include pip support
2116
2. include test support
@@ -26,7 +21,7 @@ the expectation is that between Project Mu and TianoCore Edk2 you could use any
2621
1. Download latest Git For Windows from <https://git-scm.com/download/win>
2722

2823
``` cmd
29-
https://github.com/git-for-windows/git/releases/download/v2.37.3.windows.1/Git-2.37.3-64-bit.exe
24+
https://github.com/git-for-windows/git/releases/download/v2.50.0.windows.2/Git-2.50.0.2-64-bit.exe
3025
```
3126
3227
2. It is recommended you use the following options:

docs/CodeDevelopment/rust_build.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,31 +25,31 @@ It is recommended to:
2525
4. Install the desired Rust tool chain. The version is found in the `rust-toolchain.toml` file at the root of any
2626
Project Mu repository that contains Rust code.
2727

28-
- [Example](https://github.com/microsoft/mu_tiano_platforms/blob/main/rust-toolchain.toml): `1.73.0 x86_64 toolchain`
28+
- [Example](https://github.com/microsoft/mu_tiano_platforms/blob/main/rust-toolchain.toml): `1.85.0 x86_64 toolchain`
2929

3030
- Windows:
3131

32-
\>`rustup toolchain install 1.73.0-x86_64-pc-windows-msvc`
32+
\>`rustup toolchain install 1.85.0-x86_64-pc-windows-msvc`
3333

34-
\>`rustup component add rust-src --toolchain 1.73.0-x86_64-pc-windows-msvc`
34+
\>`rustup component add rust-src --toolchain 1.85.0-x86_64-pc-windows-msvc`
3535

3636
- Linux:
3737

38-
\>`rustup toolchain install 1.73.0-x86_64-unknown-linux-gnu`
38+
\>`rustup toolchain install 1.85.0-x86_64-unknown-linux-gnu`
3939

40-
\>`rustup component add rust-src --toolchain 1.73.0-x86_64-unknown-linux-gnu`
40+
\>`rustup component add rust-src --toolchain 1.85.0-x86_64-unknown-linux-gnu`
4141

4242
5. [Install `cargo binstall`](https://github.com/cargo-bins/cargo-binstall?tab=readme-ov-file#installation)
4343

4444
6. Install `cargo make`. The required version is found in the `rust-toolchain.toml` file at the root of any Project
4545
Mu repository that contains rust code.
4646

47-
\>`cargo binstall --force cargo-make --version 0.37.9`
47+
\>`cargo binstall --force cargo-make --version 0.37.24`
4848

4949
7. Install `cargo tarpaulin`. The required version is found in the `rust-toolchain.toml` file at the root of any Project
5050
Mu repository that contains rust code.
5151

52-
\>`cargo binstall --force cargo-tarpaulin --version 0.31.2`
52+
\>`cargo binstall --force cargo-tarpaulin --version 0.31.5`
5353

5454
At this point, the essential Rust applications are installed, and a repo can begin to add and build Rust code.
5555

docs/DeveloperDocs/build_community_docs.md

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
# Building Community Docs
22

33
!!! info
4-
Today this process has been validated for use on Windows 10. This setup process is expected to roughly the same on
5-
other operating systems
6-
and none of the actual documentation source or tools should have any OS dependency.
4+
Today this process has been validated for use on Windows 11. This setup process is expected to roughly the same on
5+
other operating systems and none of the actual documentation source or tools should have any OS dependency.
76

87
## Get the docs repository
98

@@ -15,8 +14,7 @@ git clone https://github.com/Microsoft/mu.git
1514

1615
## Install required tools
1716

18-
1. Install python (Current suggested version is 3.7.x). Current min requirement is python 3.4+. Checkout python.org for
19-
directions.
17+
1. Install python. Recommended version can be viewed on [mu_devops](https://github.com/microsoft/mu_devops/blob/main/.sync/Version.njk).
2018
2. Install pip. Generally, this is done when installing python but can also be done as its own process.
2119
Details here <https://pip.pypa.io/en/stable/installing/#do-i-need-to-install-pip>
2220
3. Update pip.
Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Pulling Upstream Changes into Project Mu Repositories
2+
3+
Project Mu is based on the upstream EDK2 project, which serves as its foundational codebase. The EDK2 community actively accepts bug fixes and code improvements, ensuring a robust and evolving platform. Sometimes, changes that are merged into EDK2 need to be added to Project Mu before the next scheduled integration. This document describes the process for applying such upstream changes to Project Mu in a manner that enables maintainers to track the provenance of the commits.
4+
5+
## Cherry-Pick Process
6+
7+
To cherry-pick changes from the EDK2 repository into a Project Mu repository, follow these steps:
8+
9+
1. **Identify the Commit(s):**
10+
- Locate the commit hash(es) in the EDK2 repository that you want to apply to Project Mu.
11+
12+
2. **Sync Your Local Repository:**
13+
- Ensure your local Project Mu repository is up to date:
14+
15+
```sh
16+
git checkout <target-branch>
17+
git pull origin <target-branch>
18+
```
19+
20+
3. **Add the EDK2 Remote (if not already added):**
21+
22+
```sh
23+
git remote add edk2 https://github.com/tianocore/edk2.git
24+
git fetch edk2
25+
```
26+
27+
4. **Cherry-Pick the Commit(s):**
28+
- Use the commit hash from EDK2:
29+
30+
```sh
31+
git cherry-pick <edk2-commit-hash> -x
32+
```
33+
34+
- If conflicts arise, resolve them, then continue:
35+
36+
```sh
37+
git add <resolved-files>
38+
git cherry-pick --continue
39+
```
40+
41+
- Ammend the commit message to contain `[Cherry-Pick]` in the title.
42+
43+
```sh
44+
git commit --amend
45+
```
46+
47+
5. **Document the Change:**
48+
- In the commit message, reference the original EDK2 commit hash and provide a brief description.
49+
- Example:
50+
51+
```sh
52+
[Cherry-pick] <original commit title>
53+
```
54+
55+
6. **Push the Changes:**
56+
57+
```sh
58+
git push origin <target-branch>
59+
```
60+
61+
7. **Create a Pull Request:**
62+
- Open a pull request in the Project Mu repository.
63+
- Clearly indicate that this is a cherry-pick from EDK2 and link to the original commit(s).
64+
65+
This process ensures traceability and helps maintainers track upstream changes integrated into Project Mu.
66+
67+
## Handling Merge Commits
68+
69+
When cherry-picking from EDK2, you may encounter merge commits. These require special handling because `git cherry-pick` does not support merge commits directly. Here are some resources and strategies for dealing with them:
70+
71+
- [Git Documentation: Cherry-pick a merge commit](https://git-scm.com/docs/git-cherry-pick#_cherry_picking_a_merge_commit)
72+
- [Git Documentation: Resolving merge conflicts](https://git-scm.com/docs/git-merge#_how_conflicts_are_presented)
73+
74+
These resources provide detailed guidance and examples for handling merge commits during upstream integration.

docs/How/contributing.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ sample driver that exposes the issue with steps to reproduce the problem is idea
2626
### Reporting security issues and bugs
2727

2828
Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC)
29-
secure@microsoft.com. You should receive a response within 24 hours. If for some reason you do not, please follow up
29+
<secure@microsoft.com>. You should receive a response within 24 hours. If for some reason you do not, please follow up
3030
via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found
3131
in the [Security TechCenter](https://technet.microsoft.com/en-us/security/ff852094.aspx).
3232

@@ -59,6 +59,7 @@ That is it. Thanks for contributing.
5959
1. [Code Development](../CodeDevelopment/overview.md)
6060
2. [Tests Development](../CodeDevelopment/test.md)
6161
3. [Documentation Development](../DeveloperDocs/developer_docs.md)
62+
4. [Cherry-Picking Changes](../DeveloperDocs/pulling_upstream_changes.md)
6263

6364
### Contributor License Agreement (CLA)
6465

mkdocs_base.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ nav:
7272
- Sample Syntax: "DeveloperDocs/doc_sample_test.md"
7373
- Doc Framework Attribution: "DeveloperDocs/attribution.md"
7474
- Documentation Requirements: "DeveloperDocs/requirements.md"
75+
- Cherry-Picking: "DeveloperDocs/pulling_upstream_changes.md"
7576
- Developing Code:
7677
- Overview: "CodeDevelopment/overview.md"
7778
- Tools and Prerequisite: "CodeDevelopment/prerequisites.md"

0 commit comments

Comments
 (0)