Skip to content

Commit 5bd6a16

Browse files
Validate and update some documentation (#8959)
1 parent 3a0da34 commit 5bd6a16

File tree

2 files changed

+137
-136
lines changed

2 files changed

+137
-136
lines changed

CONTRIBUTING.md

+21-21
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,17 @@
66

77
Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
88

9-
Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [MIT](LICENSE.md).
9+
Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [MIT](LICENSE.md) license.
1010

11-
Please note that this project is released with a [Contributor Code of Conduct][code-of-conduct]. By participating in this project you agree to abide by its terms.
11+
Please note that this project is released with a [Contributor Code of Conduct][code-of-conduct]. By participating in this project, you agree to abide by its terms.
1212

1313
## Submitting a pull request
1414

15-
1. [Fork][fork] and clone the repository
16-
1. Create a new branch: `git checkout -b my-branch-name`
17-
1. Make your changes, ensure that they include steps to install, validate post-install and update software report (please see [How to add new tool](CONTRIBUTING.md#how-to-add-new-tool) for details).
18-
1. Test your changes by [creating image and deploying a VM](docs/create-image-and-azure-resources.md).
19-
1. Push to your fork and [submit a pull request][pr]
15+
1. [Fork][fork] and clone the repository.
16+
1. Create a new branch: `git checkout -b my-branch-name`.
17+
1. Make your changes, ensuring that they include steps to install, validate post-install, and update the software report (please see [How to add a new tool](CONTRIBUTING.md#how-to-add-a-new-tool) for details).
18+
1. Test your changes by [creating an image and deploying a VM](docs/create-image-and-azure-resources.md).
19+
1. Push to your fork and [submit a pull request][pr].
2020

2121
Here are a few things you can do that will increase the likelihood of your pull request being accepted:
2222

@@ -25,40 +25,40 @@ Here are a few things you can do that will increase the likelihood of your pull
2525
- Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
2626
- Write [good commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
2727
- For new tools:
28-
- Make sure that the tool satisfies [Software Guidelines](README.md#software-guidelines).
29-
- Create an issue and get an approval from us to add this tool to the image before creating the pull request.
28+
- Make sure that the tool satisfies the [Software Guidelines](README.md#software-guidelines).
29+
- Create an issue and get approval from us to add this tool to the image before creating the pull request.
3030

31-
## How to add new tool
31+
## How to add a new tool
3232

3333
### General rules
3434

35-
- For every new tool add validation scripts and update software report script to make sure that it is included to documentation
36-
- If the tool is available in other platforms (macOS, Windows, Linux), make sure you include it in as many as possible.
37-
- If installing a few versions of the tool, consider putting the list of versions in the corresponding `toolset.json` file. It will help other customers to configure their builds flexibly. See [toolset-windows-2019.json](images/windows/toolsets/toolset-2019.json) as example.
38-
- Use consistent naming across all files
39-
- Validation scripts should be simple and shouldn't change image content
35+
- For every new tool, add validation scripts and update the software report script to ensure that it is included in the documentation.
36+
- If the tool is available on multiple platforms (macOS, Windows, Linux), make sure you include it on as many as possible.
37+
- If installing multiple versions of the tool, consider putting the list of versions in the corresponding `toolset.json` file. This will help other customers configure their builds flexibly. See [toolset-windows-2019.json](images/windows/toolsets/toolset-2019.json) as an example.
38+
- Use consistent naming across all files.
39+
- Validation scripts should be simple and shouldn't change the image content.
4040

4141
### Windows
4242

4343
- Add a script that will install the tool and put the script in the `scripts/build` folder.
4444
There are a bunch of helper functions that could simplify your code: `Install-ChocoPackage`, `Install-Binary`, `Install-VSIXFromFile`, `Install-VSIXFromUrl`, `Invoke-DownloadWithRetry`, `Test-IsWin19`, `Test-IsWin22` (find the full list of helpers in [ImageHelpers.psm1](images/windows/scripts/helpers/ImageHelpers.psm1)).
4545
- Add a script that will validate the tool installation and put the script in the `scripts/tests` folder.
4646
We use [Pester v5](https://github.com/pester/pester) for validation scripts. If the tests for the tool are complex enough, create a separate `*.Tests.ps1`. Otherwise, use `Tools.Tests.ps1` for simple tests.
47-
Add `Invoke-PesterTests -TestFile <testFileName> [-TestName <describeName>]` at the end of the installation script to make sure that your tests will be run.
47+
Add `Invoke-PesterTests -TestFile <testFileName> [-TestName <describeName>]` at the end of the installation script to ensure that your tests will be run.
4848
- Add changes to the software report generator `images/windows/scripts/docs-gen/Generate-SoftwareReport.ps1`. The software report generator is used to generate an image's README file, e.g. [Windows2019-Readme.md](images/windows/Windows2019-Readme.md) and uses [MarkdownPS](https://github.com/Sarafian/MarkdownPS).
4949

5050
### Ubuntu
5151

52-
- Add script that will install and validate the tool and put the script in the `scripts/build` folder.
52+
- Add a script that will install and validate the tool and put the script in the `scripts/build` folder.
5353
Use existing scripts such as [github-cli.sh](images/ubuntu/scripts/build/github-cli.sh) as a starting point.
54-
- Use [helpers](images/ubuntu/scripts/helpers/install.sh) to simplify installation process.
55-
- Validation part should `exit 1` if any issue with installation.
54+
- Use [helpers](images/ubuntu/scripts/helpers/install.sh) to simplify the installation process.
55+
- The validation part should `exit 1` if there is any issue with the installation.
5656
- Add changes to the software report generator `images/ubuntu/scripts/docs-gen/Generate-SoftwareReport.ps1`. The software report generator is used to generate an image's README file, e.g. [Ubuntu2004-Readme.md](images/ubuntu/Ubuntu2004-README.md) and it uses [MarkdownPS](https://github.com/Sarafian/MarkdownPS).
5757

5858
### macOS
5959

60-
macOS source lives in this repository and available for everyone. However, macOS image-generation CI doesn't support external contributions yet so we are not able to accept pull-requests for now.
61-
We are in the process of preparing macOS CI to accept contributions. Until then, we appreciate your patience and ask you continue to make tool requests by filing issues.
60+
The macOS source lives in this repository and is available for everyone. However, the macOS image-generation CI doesn't support external contributions yet, so we are not able to accept pull requests for now.
61+
We are in the process of preparing the macOS CI to accept contributions. Until then, we appreciate your patience and ask that you continue to make tool requests by filing issues.
6262

6363
## Resources
6464

0 commit comments

Comments
 (0)