From bd059a782d1ecb299304ea636391edd05d39fa05 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Sun, 15 Sep 2024 14:46:17 +0200 Subject: [PATCH 1/2] document --from-commit and --include-easyblocks-from-commit --- docs/integration-with-github.md | 47 ++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/docs/integration-with-github.md b/docs/integration-with-github.md index 77f6f2c2b..3a12a27e2 100644 --- a/docs/integration-with-github.md +++ b/docs/integration-with-github.md @@ -16,9 +16,10 @@ are a couple of requirements: - **a GitHub user name** - only required for authenticated access to the GitHub API, which can help to avoid rate limitations - - *not* strictly necessary for read-only operations - - i.e. *not* required for [Using easyconfigs from pull requests][github_from_pr] and - [Reviewing easyconfig pull requests][github_review_pr] + - *not* (strictly) necessary for read-only operations, including: + - [Using easyconfigs from pull requests (`--from-pr`)][github_from_pr]; + - [Using easyconfigs from commits (`--from-commit`)][github_from_commit]; + - [Reviewing easyconfig pull requests (`--review-pr`][github_review_pr]; - see [Providing a GitHub username][github_user] - **a GitHub token** + `keyring` **Python package** - install via `pip install keyring` (for Python2: `pip install 'keyring<19.0'`) @@ -29,6 +30,7 @@ are a couple of requirements: permissions - i.e. for [Uploading test reports][github_upload_test_report] and [Submitting pull requests][github_new_pr] + - *not* used for [Using easyconfig from commits][github_from_commit] - see [Installing a GitHub token][github_token] - `git` **command** / `GitPython` **Python package** - install via `pip install GitPython` (for Python2: @@ -362,6 +364,35 @@ Dry run: printing build status of easyconfigs and dependencies Again, note that locally available easyconfigs that are required to resolve dependencies are being picked up as needed. +## Using easyconfigs from a commit {: #github_from_commit } + +*(`--from-commit`, supported since EasyBuild v4.9.1)* + +Using `--from-commit`, you can let EasyBuild use easyconfig files that were added or modified in a specific Git commit. + +This is similar to using `--from-pr` (see [Using easyconfigs from pull requests][github_from_pr]), but it differs in two ways: + +- The GitHub API is *not* used to obtain the easyconfig files from a particular commit. This can be important since + it avoids hitting the [GitHub API rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api), + especially when no GitHub token is available; + +- The easyconfig files will be *exactly* those as they are in the specified commit, + as they can also be consulted [on GitHub](https://github.com/easybuilders/easybuild-easyconfigs/tree/c0ff3315c0ffeec0ff3315c0ffeec0ffeec0ff33/easybuild/easyconfigs) + (link points to a fictious commit SHA `c0ff3315c0ffeec0ff3315c0ffeec0ffeec0ff33`). + This is not the case with `--from-pr`, since then either the PR branch is merged with the target branch + (typically `develop`) before obtained the easyconfigs (for open PRs), or the `develop` branch is used (for merged PRs). + This aspect can be important to ensure reproducibility. + +!!! note + The commit SHA passed to `--from-commit` must be a full commit SHA consisting of 40 characters, + not a 10-character shortered commit SHA as you often see in GitHub. + +Example usage: +```shell +# use easyconfig file for EasyBuild v4.9.3 which was contributed in https://github.com/easybuilders/easybuild-easyconfigs/pull/21412 +eb --from-commit 82206bb1c68d8d9ccd551b36efb0a0cc2251147c EasyBuild-4.9.3.eb +``` + ## Using easyblocks from pull requests {: #github_include_easyblocks_from_pr } *(`--include-easyblocks-from-pr`, supported since EasyBuild v4.2.0)* @@ -397,6 +428,16 @@ EasyBlock (easybuild.framework.easyblock) ... ``` +## Using easyblocks from a commit {: #github_include_easyblocks_from_commit } + +*(`--include-easyblocks-from-commit`, supported since EasyBuild v4.9.1)* + +Using `--include-easyblocks-from-commit`, you can let EasyBuild use easyblocks exactly +as they were in a particular commit. + +This differs from using `--include-easyblocks-from-pr` in the same way as using `--from-commit` differs from using +`--from-commit`, see also [Using easyconfigs from a commit][github_from_commit]. + ## Uploading test reports {: #github_upload_test_report } *(`--upload-test-report`, supported since EasyBuild v1.13.0)* From 9973da5436fd12b9cabea936eff6748d51883b35 Mon Sep 17 00:00:00 2001 From: Kenneth Hoste Date: Sun, 15 Sep 2024 15:51:04 +0200 Subject: [PATCH 2/2] apply Simon's suggestions Co-authored-by: Simon Branford <4967+branfosj@users.noreply.github.com> --- docs/integration-with-github.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/integration-with-github.md b/docs/integration-with-github.md index 3a12a27e2..3fd88db84 100644 --- a/docs/integration-with-github.md +++ b/docs/integration-with-github.md @@ -376,18 +376,19 @@ This is similar to using `--from-pr` (see [Using easyconfigs from pull requests] it avoids hitting the [GitHub API rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api), especially when no GitHub token is available; -- The easyconfig files will be *exactly* those as they are in the specified commit, - as they can also be consulted [on GitHub](https://github.com/easybuilders/easybuild-easyconfigs/tree/c0ff3315c0ffeec0ff3315c0ffeec0ffeec0ff33/easybuild/easyconfigs) - (link points to a fictious commit SHA `c0ff3315c0ffeec0ff3315c0ffeec0ffeec0ff33`). +- The easyconfig files will be *exactly* as they are in the specified commit + and they can also be consulted [on GitHub](https://github.com/easybuilders/easybuild-easyconfigs/tree/c0ff3315c0ffeec0ff3315c0ffeec0ffeec0ff33/easybuild/easyconfigs) + (link points to a fictitious commit SHA `c0ff3315c0ffeec0ff3315c0ffeec0ffeec0ff33`). This is not the case with `--from-pr`, since then either the PR branch is merged with the target branch (typically `develop`) before obtained the easyconfigs (for open PRs), or the `develop` branch is used (for merged PRs). This aspect can be important to ensure reproducibility. !!! note The commit SHA passed to `--from-commit` must be a full commit SHA consisting of 40 characters, - not a 10-character shortered commit SHA as you often see in GitHub. + not a the first part of a commit SHA as you often see in GitHub. Example usage: + ```shell # use easyconfig file for EasyBuild v4.9.3 which was contributed in https://github.com/easybuilders/easybuild-easyconfigs/pull/21412 eb --from-commit 82206bb1c68d8d9ccd551b36efb0a0cc2251147c EasyBuild-4.9.3.eb