Skip to content

Commit

Permalink
Update installation instructions
Browse files Browse the repository at this point in the history
The instructions haven't kept up with recent changes to the tools.
  • Loading branch information
BillWagner committed May 13, 2024
1 parent 13d0036 commit 2f92df4
Show file tree
Hide file tree
Showing 2 changed files with 19 additions and 32 deletions.
23 changes: 12 additions & 11 deletions WhatsNew.Cli/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,10 @@ Metrics for the "what's new" pages are made available at [aka.ms/whatsnewindocs]

## Usage

You can use the tool from the command line, or as a GitHub action. If you run on the command line, the tool generates the changes for a new article on your machine. If you run as a GitHub action, the action opens a PR for you. THe only functional difference in the output is that the GitHub action filters Microsoft FTEs from the contributor list. The command line version doesn't due to access rights.

To use the tool as a command line executable:

1. Clone the `dotnet/docs-tools` repository.
1. Generate a PAT per the instructions at [Creating a token](https://help.github.com/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line#creating-a-token). When selecting scopes for the PAT, check the following boxes:
- For private repos:
Expand All @@ -31,17 +35,8 @@ Metrics for the "what's new" pages are made available at [aka.ms/whatsnewindocs]
- **admin:org** > **read:org**
1. For private repos in the *MicrosoftDocs* GitHub organization, after generating the PAT, select **Enable SSO** and choose **Authorize** for the **MicrosoftDocs**.
1. Store the PAT in an environment variable named `GitHubKey`.
1. Set up an OSPO personal access token
> This step is required for versions 2.0 and above.

The OSPO personal access token is required to access the OSPO API. This API determines community contributors and Microsoft employee and vendor contributors.
1. Request a token at [Visual Studio Online](https://ossmsft.visualstudio.com/_usersSettings/tokens). You can disable all scopes *except* read:user profile.
1. Store the token in an environment variable named "OspoKey". **If you are using the GitHub Action to generate the PR automatically**, add the key as a secret in your repository:
- Go to **Settings** on your repo.
- Select **Secrets**
- Add "OSPO_KEY" as a **Repository Secret**.
1. Install the [.NET SDK 7.0](https://dotnet.microsoft.com/download/dotnet) or later.
1. build and publish the tool. The `WhatsNew.Cli` folder is at the root of the repository you closed in step 1. By default, this builds the *Debug* configuration.
1. Install the [.NET SDK 8.0](https://dotnet.microsoft.com/download/dotnet) or later.
1. build and publish the tool. The `WhatsNew.Cli` folder is at the root of the repository you closed in step 1. By default, this builds the *Debug* configuration.

```bash
cd ./WhatsNew.Cli
Expand All @@ -56,6 +51,12 @@ Metrics for the "what's new" pages are made available at [aka.ms/whatsnewindocs]
dotnet ../docs-tools/WhatsNew.Cli/bin/Debug/net7.0/publish/WhatsNew.dll --owner MicrosoftDocs --repo visualstudio-docs-pr --savefile ./docs/ide/whats-new-visual-studio-docs.md
```

To use the tool as an action:

1. Configure the registered `CLIENT_ID`, `TENANT_ID` and `OSMP_API_AUDIENCE` keys in your repository. Ask the "what's new" admins for the values.
1. Request app registration for your repo / branch pair.
1. A the `whats-new.yml` file in the `.github/Workflows` folder of your repo. The file should generally follow the form in the [dotnet/docs](https://github.com/dotnet/docs/blob/main/.github/workflows/whats-new.yml) version.

### Examples

**Display the help menu:**
Expand Down
28 changes: 7 additions & 21 deletions actions/sequester/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,12 +23,15 @@ To install the GitHub actions:

- **SEQUESTER_APPID**: This is the app ID for the Sequester Action. Get this from one of the App admins (Bill or Immo).
- **SEQUESTER_PRIVATEKEY**: This is the private key to authorize sequester. Get this from one of the App admins (Bill or Immo).
- **OSPO_KEY**: Generate a PAT at [OSSMSFT](https://ossmsft.visualstudio.com/_usersSettings/tokens) with the following permissions:
- *UserProfile*: Read
- **QUEST_KEY**: Generate a PAT at [MSFT-SKILLING](https://dev.azure.com/msft-skilling/_usersSettings/tokens) with the following permissions:
- *Identity*: Read
- *Project & Team*: Read/Write
- *WorkItems*: Read/Write
- **CLIENT_ID**: The client ID used for secretless authentication
- **TENANT_ID**: The Tenant ID used for secretless authentication
- **OSMP_API_AUDIENCE**: The audience resource ID used for secretless authentication

> **Note:** To configure GitHub Action secrets, see [GitHub Docs: Encrypted secrets](https://docs.github.com/actions/security-guides/encrypted-secrets).
1. ***Start applying labels***
- Add the trigger label to any issue, and it will be imported into Quest.
Expand All @@ -38,11 +41,7 @@ To install the GitHub actions:
## Suggestions for future releases

- [ ] Populate the "GitHub Repo" field in Azure DevOps to make reporting by repository easier.
- [X] Add Epics (configurable) as a parent of user stories on import.
- [X] Update the label block in Quest when an issue is closed. That way, any "OKR" labels get added when the work item is completed. This would be a simplified version of updating all labels when labels are added or removed.
- [ ] Integrate with Repoman. That tool already performs a number of actions on different events in the repo. The code underlying these events could be ported there.
- [ ] Encapsulate services into their own projects/packages, and share them as needed.
- [X] Use DI where applicable, enabling `IHttpClientFactory`, Polly (for transient fault handling), `IOptions<T>` pattern, and easier testing.

## Triggers

Expand Down Expand Up @@ -77,22 +76,9 @@ The consuming repository would ideally define the config file. As an example, it
}
```

This config file would override the defaults, enabling consuming repositories to do as they please. In addition to this JSON config, there would need to be three environment variables set:

- `ImportOptions__ApiKeys__GitHubToken`
- `ImportOptions__ApiKeys__OSPOKey`
- `ImportOptions__ApiKeys__QuestKey`

These env vars would be assigned to from the consuming repository secrets, as follows (likely in a workflow file named _quest-import.yml_):

```yaml
env:
ImportOptions__ApiKeys__GitHubToken: ${{ secrets.GITHUB_TOKEN }}
ImportOptions__ApiKeys__OSPOKey: ${{ secrets.OSPO_API_KEY }}
ImportOptions__ApiKeys__QuestKey: ${{ secrets.QUEST_API_KEY }}
```
## Workflow files

> **Note:** To configure GitHub Action secrets, see [GitHub Docs: Encrypted secrets](https://docs.github.com/actions/security-guides/encrypted-secrets).
Create a PR that adds two workflows into your repository: One to sequester a single issue on demand; the other to bulk import all issues modified in the last N days. In almost all cases, you can copy the versions of [quest.yml](https://github.com/dotnet/docs-tools/blob/main/.github/workflows/quest.yml) and [quest-bulk.yml](https://github.com/dotnet/docs-tools/blob/main/.github/workflows/quest-bulk.yml) files. These files are stored in your repositories `.github/workflows` folder.

## Field mapping

Expand Down

0 comments on commit 2f92df4

Please sign in to comment.