Skip to content

Commit

Permalink
Merge pull request #274 from boegel/from_commit
Browse files Browse the repository at this point in the history
document `--from-commit` and `--include-easyblocks-from-commit`
  • Loading branch information
branfosj authored Sep 15, 2024
2 parents b39f037 + 9973da5 commit 9eb59f9
Show file tree
Hide file tree
Showing 2 changed files with 46 additions and 4 deletions.
48 changes: 45 additions & 3 deletions docs/integration-with-github.md
Original file line number Diff line number Diff line change
Expand Up @@ -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'`)
Expand All @@ -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:
Expand Down Expand Up @@ -362,6 +364,36 @@ 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* 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 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
```

## Using easyblocks from pull requests {: #github_include_easyblocks_from_pr }

*(`--include-easyblocks-from-pr`, supported since EasyBuild v4.2.0)*
Expand Down Expand Up @@ -397,6 +429,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)*
Expand Down
2 changes: 1 addition & 1 deletion docs/release-notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ bugfix/update release
- add support for `--software-commit` and an associated template `%(software_commit)s` ([#4628](https://github.com/easybuilders/easybuild-framework/pull/4628))
- various bug fixes, including:
- correctly evaluate result for `--dep-graph` ([#4554](https://github.com/easybuilders/easybuild-framework/pull/4554))
- fix fetch progress bar showing to many files ([#4568](https://github.com/easybuilders/easybuild-framework/pull/4568))
- fix fetch progress bar showing too many files ([#4568](https://github.com/easybuilders/easybuild-framework/pull/4568))
- resolve internal for imkl>=2021 version subdir via "latest" symlink ([#4570](https://github.com/easybuilders/easybuild-framework/pull/4570))
- fix typo in message about including an easyblock from a commit ([#4575](https://github.com/easybuilders/easybuild-framework/pull/4575))
- don't use special flags for `strict`, `precise`, `loose`, `veryloose` toolchain options on RISC-V ([#4576](https://github.com/easybuilders/easybuild-framework/pull/4576))
Expand Down

0 comments on commit 9eb59f9

Please sign in to comment.