Skip to content

Add GitHub Action workflow to update man pages #48784

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.

Sign up for GitHub

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add GitHub Action workflow to update man pages #48784

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
39 changes: 39 additions & 0 deletions .github/workflows/update-man-pages.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
name: Update man-pages workflow
on:
Copy link
Member

Choose a reason for hiding this comment

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

if we change this to be a manually-triggered workflow, then the username question for the commit that's created has an easy answer - the name/email of the user that triggered the action

schedule:
- cron: "42 3 1/15 * *" # Trigger every 15 days at 03:42
Copy link
Member Author

Choose a reason for hiding this comment

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

Is running an update twice a month too frequent?

Copy link
Member

Choose a reason for hiding this comment

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

this is cheap enough that it seems reasonable to me

#- cron: "0,5,10,15,20,25,30,35,40,45,50,55 * * * *" # For testing

permissions:
contents: write
pull-requests: write

jobs:
update-man-pages:
runs-on: ubuntu-latest
steps:
- name: Checkout repository code
uses: actions/checkout@v4

- name: Update man-pages
run: |
set -euo pipefail

rm ./documentation/manpages/sdk/*
Copy link
Member Author

Choose a reason for hiding this comment

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

Deleting everything allows stale pages to be removed.


./documentation/manpages/tool/run_docker.sh

if [[ -n $(git status -s) ]]; then
git config user.name 'TODO'
Copy link
Member

Choose a reason for hiding this comment

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

I think it's very common to use the combination of:

git config user.name "github-actions"
git config user.email "github-actions@github.com"

e.g:

https://github.com/dotnet/msbuild/blob/1e7a0a86776c87955d195980fa1873447a3341af/.github/workflows/SyncAnalyzerTemplateMSBuildVersion.yml#L131-L134

Copy link
Member

Choose a reason for hiding this comment

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

This makes sense to me!

git config user.email 'TODO@example.com'
Comment on lines +27 to +28
Copy link
Member Author

Choose a reason for hiding this comment

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

Are there any standard/recommended name/email combinations I can use?

Copy link
Member

Choose a reason for hiding this comment

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

see my comment about the workflow trigger above. I don't think we have any names/aliases readily available for recurring cleanup-style work

Copy link
Member

Choose a reason for hiding this comment

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

We have a precedence:

eng/common/core-templates/steps/source-build.yml:        git config user.email dn-bot@microsoft.com
eng/common/core-templates/steps/source-build.yml-        git config user.name dn-bot
--
eng/pipelines/templates/steps/vmr-pull-updates.yml-    git config --global user.name "dotnet-maestro[bot]"
eng/pipelines/templates/steps/vmr-pull-updates.yml:    git config --global user.email "dotnet-maestro[bot]@users.noreply.github.com"

I think the idea is to run it automatically so we don't forget to update (we frequently forget to update the manpages).

Copy link
Member

Choose a reason for hiding this comment

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

I wouldn't want to re-use those names without checking with the arcade and/or MS source-build teams first - we (SDK) don't control those identities and I wouldn't want to muddy contributions.

Copy link
Member

Choose a reason for hiding this comment

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

cc @dotnet/product-construction. Could we tie the triggering to the release cadence? i.e. add to the list of prerequisites of release (both previews and GA). Job only took 42s to complete https://github.com/omajid/dotnet-sdk/actions/runs/14769460163.

date=$(date +%F)
git add .
title="Update man pages"
branch=update-man-page-$date
git checkout -b $branch
git commit -a -m "$title"
git push -u origin $branch --force
Copy link
Member

Choose a reason for hiding this comment

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

Is there a reason we are using --force here? The branch is newly created

gh pr create --base main --head $branch --title "$title" --body "Auto-generated"
Copy link
Member

Choose a reason for hiding this comment

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

Maybe we could add an [automated] prefix to the title for extra clarity?

Maybe we could add some additional details to the PR body?

Suggested change
gh pr create --base main --head $branch --title "$title" --body "Auto-generated"
gh pr create --base main --head $branch --title "[automated] $title" --body "This action is executed twice a month to automatically update the manpages based on latest changes to the repo"

fi
env:
GH_TOKEN: ${{ github.token }}
2 changes: 1 addition & 1 deletion documentation/manpages/tool/update-man-pages.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,4 +55,4 @@ ls docs-main/docs/core/tools/dotnet*.md | while read -r file;
"$file" -o "${command_name}"."${man_page_section}"
done

# rm -rf docs-main
rm -rf docs-main
Copy link
Member Author

Choose a reason for hiding this comment

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

This is a sub-repo (or a subdirectory) that we never want to git add.