Skip to content

Commit 534c99c

Browse files
boegelboegel
committed
restructure documentation on EasyBuild v5.0
1 parent 4b663df commit 534c99c

9 files changed

+264
-156
lines changed

‎docs/easybuild-v5/backwards-incompatible-changes.md

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Backwards-incompatible changes in EasyBuild v5.0
2+
3+
*(for a full overview of changes in EasyBuild v5.0, see [here](overview-of-changes.md))*
4+
5+
A number of *backwards-incompatible* changes are being made in EasyBuild v5.0:
6+
7+
* [Support for Python 2.7 is removed, Python 3.6+ is required][py36]
8+
* [Deprecated EasyBuild bootstrap script is removed][bootstrap_script]
9+
* [Experimental support for the `.yeb` easyconfig format is removed][yeb]
10+
11+
---
12+
13+
## Support for Python 2.7 is removed, Python 3.6+ is required {: #py36 }
14+
15+
EasyBuild 5.0 requires Python >= 3.6 to run.
16+
17+
Running EasyBuild with Python 2.7 or a Python 3 version older than Python 3.6 is no longer supported.
18+
19+
Trying to run EasyBuild with a Python version that is too old will result in an error:
20+
21+
```log
22+
ERROR: No compatible 'python' command found via $PATH (EasyBuild requires Python 3.6+)
23+
```
24+
25+
Python 2.7 has been [end-of-life since 1 Jan 2020](https://www.python.org/doc/sunset-python-2),
26+
and dropping compatibility with Python 2.7 and Python 3.5 enabled some significant code cleanup
27+
(see [easybuild-framework PR #4229](https://github.com/easybuilders/easybuild-framework/pull/4229)).
28+
29+
The [results of the 6th EasyBuild User Survey (2022)](https://easybuild.io/user_survey) show that the impact of
30+
this breaking change on the EasyBuild community should be very limited, since:
31+
32+
* Only ~13% of survey participants were still running EasyBuild on top of Python 2.7;
33+
* No survey participants reported using Python 3.5;
34+
* Over 85% of survey participants reported using Python 3.6, or a more recent version of Python 3;
35+
* Only 3 out of 118 survey participants (~2.5%) reported that dropping support for running EasyBuild
36+
on top of Python 2 would be *problematic* for them;
37+
38+
Along with actively removing code that was only required to retain compatibility with Python 2.7 or 3.5,
39+
the `easybuild.tools.py2vs3` module that was introduced to facilitate supporting both Python 2.7 and Python 3
40+
has been deprecated (see also [here](deprecated-functionality.md#py2vs3)).
41+
42+
---
43+
44+
## Deprecated EasyBuild bootstrap script is removed {: #bootstrap_script }
45+
46+
The EasyBuild bootstrap script has been removed (see [easybuild-framework PR #4233](https://github.com/easybuilders/easybuild-framework/pull/4233)).
47+
48+
Please see the [installation page](../installation.md) for the suggested methods for installing EasyBuild.
49+
50+
---
51+
52+
## Experimental support for the .yeb easyconfig format is removed {: #yeb }
53+
54+
Support for the experimental `.yeb` easyconfig format has been removed (see [easybuild-framework PR #4237](https://github.com/easybuilders/easybuild-framework/pull/4237)).
55+
56+
This format allowed easyconfigs to be specified in YAML. However, there has been no recent development of this
57+
format and little suggestion that anyone was using it at all.

‎docs/easybuild-v5/deprecated-functionality.md

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Deprecated functionality in EasyBuild v5.0
2+
3+
*(for a full overview of changes in EasyBuild v5.0, see [here](overview-of-changes.md))*
4+
5+
Some functionality is being deprecated in EasyBuild v5.0, and will no longer be supported in EasyBuild v6.0:
6+
7+
* [`run_cmd` and `run_cmd_qa` functions][run_cmd]
8+
* [`easybuild.tools.py2vs3` module][py2vs3]
9+
10+
If you trigger any deprecated functionality when using EasyBuild v5.0, a warning message will be printed.
11+
12+
---
13+
14+
## `run_cmd` and `run_cmd_qa` functions {: #run_cmd }
15+
16+
The `run_cmd` and `run_cmd_qa` functions will be deprecated.
17+
18+
You should migrate to the new [`run_shell_cmd`](run_shell_cmd.md) function instead.
19+
20+
21+
---
22+
23+
## `easybuild.tools.py2vs3` module {: #py2vs3 }
24+
25+
[easybuild-framework PR #4229](https://github.com/easybuilders/easybuild-framework/pull/4229)
26+
27+
The following table lists the changes required to replace imports from the the `py2vs3` module.
28+
29+
| `from easybuild.tools.py2vs3 import ...` | Replacement |
30+
|--|--|
31+
| `ascii_letters` | `from string import ascii_letters` |
32+
| `ascii_lowercase` | `from string import ascii_lowercase` |
33+
| `build_opener` | `from urllib.request import build_opener` |
34+
| `ConfigParser` | `from configparser import ConfigParser` |
35+
| `configparser` | `import configparser` |
36+
| `create_base_metaclass` | `from easybuild.base.wrapper import create_base_metaclass` |
37+
| `extract_method_name` | No import required. Replace `extract_method_name(method)` with `'_'.join(method.__code__.co_names)` |
38+
| `HTMLParser` | `from html.parser import HTMLParser` |
39+
| `HTTPError` | `from urllib.request import HTTPError` |
40+
| `HTTPSHandler` | `from urllib.request import HTTPSHandler` |
41+
| `json_loads` | `from json import loads` and rename `json_loads` to `loads` |
42+
| `Mapping` | `from collections.abc import Mapping` |
43+
| `mk_wrapper_baseclass` | `from easybuild.base.wrapper import mk_wrapper_baseclass` |
44+
| `OrderedDict` | `from collections import OrderedDict` |
45+
| `raise_with_traceback` | No import required. Replace `raise_with_traceback(exception, message, tb)` with `raise exception(message).with_traceback(tb)` |
46+
| `reload` | `from importlib import reload` |
47+
| `Request` | `from urllib.request import Request` |
48+
| `string_type` | No import required. Use `str` directly. |
49+
| `StringIO` | `from io import StringIO` |
50+
| `std_urllib` | `import urllib.request as std_urllib` |
51+
| `subprocess_popen_text` | `from easybuild.tools.run import subprocess_popen_text` |
52+
| `subprocess_terminate` | `from easybuild.tools.run import subprocess_terminate` |
53+
| `urlencode` | `from urllib.parse import urlencode` |
54+
| `URLError` | `from urllib.request import URLError` |
55+
| `urlopen` | `from urllib.request import urlopen` |
56+

‎docs/easybuild-v5/enhancements.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Enhancements in EasyBuild v5.0
2+
3+
*(for a full overview of changes in EasyBuild v5.0, see [here](overview-of-changes.md))*
4+
5+
Various significant enhancements are included in EasyBuild v5.0, including:
6+
7+
* [`run_shell_cmd` function][run_shell_cmd]
8+
* [Enable `--trace` by default][trace]
9+
10+
---
11+
12+
## `run_shell_cmd` function { : #run_shell_cmd }
13+
14+
See dedicated page on the new [`run_shell_cmd` function](run_shell_cmd.md).
15+
16+
---
17+
18+
## Enable `--trace` by default {: #trace }
19+
20+
The [`--trace` option](../tracing-progress.md) is enabled by default (see [easybuild-framework PR #4250](https://github.com/easybuilders/easybuild-framework/pull/4250)).
21+
22+
This makes the output produced by the `eb` command more informative, by providing more information about what's going on in the background.
23+
24+
To disable trace output, either:
25+
26+
* Use the `--disable-trace` command line option;
27+
* Set the `$EASYBUILD_DISABLE_TRACE` environment variable;
28+
* Disable trace mode in a [configuration file](../configuration.md#configuration_file):
29+
30+
``` ini
31+
[override]
32+
trace=0
33+
```

‎docs/easybuild-v5/index.md

+8-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# EasyBuild v5.0
22

3-
* [Overview of changes](overview-of-changes.md)
4-
* [GitHub Project board](https://github.com/orgs/easybuilders/projects/18)
5-
* [Talk on EasyBuild 5.0 at EUM'23](https://easybuild.io/eum23/#easybuild5)
3+
- [Overview of changes](overview-of-changes.md)
4+
- [Backwards-incompatible changes](backwards-incompatible-changes.md)
5+
- [Enhancements](enhancements.md)
6+
- [`run_shell_cmd` function](run_shell_cmd.md)
7+
- [Deprecated functionality](deprecated-functionality.md)
8+
- [Policies](policies.md)
9+
- [GitHub Project board](https://github.com/orgs/easybuilders/projects/18)
10+
- [Talk on EasyBuild 5.0 at EasyBuild User Meeting 2023](https://easybuild.io/eum23/#easybuild5)

‎docs/easybuild-v5/overview-of-changes.md

+15-153
Original file line numberDiff line numberDiff line change
@@ -1,168 +1,30 @@
1-
# Overview of changes in EasyBuild version 5.0 {: #overview }
1+
# Overview of changes in EasyBuild version 5.0
22

33
!!! warning
44
EasyBuild 5.0 is currently still under development, via the `5.0.x` branches in the EasyBuild GitHub repositories.
55

6-
We intend to update this page regularly as the [planned changes][eb5_plans] are being implemented and when there
7-
are [proposed changes][eb5_proposals] where we are requesting community feedback.
6+
We intend to update this section of the documentation regularly as the planned changes are being implemented,
7+
and when there are [proposed changes](proposed-changes.md) where we are requesting community feedback.
88

99
This page provides a concise overview of the most prominent changes in EasyBuild version 5.0,
1010
which can be categorized as:
1111

12-
* [Significant enhancements][significant_enhancements]
13-
* [Backward-incompatible changes][backwards_incompatible]
14-
* [Deprecated functionality][deprecated_v5]
12+
* [Enhancements](enhancements.md)
13+
* [Backward-incompatible changes](backwards-incompatible-changes.md)
14+
* [Deprecated functionality](deprecated-functionality.md)
15+
* [Proposed changes](proposed-changes.md)
16+
* [Policies](policies.md)
1517

16-
For in-depth details on a particular change, see the pull requests that are linked from each of the subsections below.
18+
For in-depth details on a particular change, see the pull requests that are linked
19+
from each of the subsections linked above.
1720

18-
---
19-
20-
## Planned and proposed changes for EasyBuild v5.0 {: #eb5_changes }
21-
22-
At the [EasyBuild User Meeting](https://easybuild.io/eum23), Simon Branford set out the
21+
At the [EasyBuild User Meeting 2023](https://easybuild.io/eum23), Simon Branford set out the
2322
[roadmap for EasyBuild v5.0](https://easybuild.io/eum23/#easybuild5).
2423

25-
### Proposed changes for EasyBuild v5.0 {: #eb5_proposals }
26-
27-
There are several proposed changes where the EasyBuild maintainers are seeking community feedback. If you wish to provide
28-
feedback then please comment in the GitHub issue for the proposal.
29-
30-
* [Minimum supported Lmod Version](https://github.com/easybuilders/easybuild/issues/871)
31-
* [Toolchain Support Policy](https://github.com/easybuilders/easybuild/issues/872)
32-
33-
### Planned changes for EasyBuild v5.0 {: #eb5_plans }
24+
To track the progress on the development of EasyBuild v5.0,
25+
see the [GitHub Project board for EasyBuild v5.0](https://github.com/orgs/easybuilders/projects/18).
3426

3527
!!! note
36-
This list is the major planned changes. It is not intended to be a complete list of all changes that are
37-
planned for EasyBuild v5.0.
38-
39-
### Tracking development of EasyBuild v5.0
40-
41-
* [GitHub Project board for EasyBuild v5.0](https://github.com/orgs/easybuilders/projects/18)
42-
43-
---
44-
45-
## Significant enhancements in EasyBuild v5.0 {: #significant_enhancements }
46-
47-
Various significant enhancements are included in EasyBuild v5.0, including:
48-
49-
* [enable `--trace` by default][eb5_trace]
50-
51-
### `--trace` enabled by default {: #eb5_trace }
52-
53-
The [`--trace` option][trace] is enabled by default (see [easybuild-framework PR #4250](https://github.com/easybuilders/easybuild-framework/pull/4250)).
54-
This makes the output produced by the `eb` command more informative, by providing more information about what's going on in the background.
55-
56-
To disable trace output, either:
57-
58-
* Use the `--disable-trace` command line option;
59-
* Set the `$EASYBUILD_DISABLE_TRACE` environment variable;
60-
* Disable trace mode in a [configuration file][configuration_file]:
61-
62-
``` ini
63-
[override]
64-
trace=0
65-
```
66-
67-
---
68-
69-
## Backwards-incompatible changes in EasyBuild v4.0 {: #backwards_incompatible }
70-
71-
A number of *backwards-incompatible* changes are being made in EasyBuild v5.0:
72-
73-
* [Support for Python 2.7 is removed -- Python 3.6+ is required][py36]
74-
* [Deprecated EasyBuild bootstrap script is removed][bootstrap_script]
75-
* [Experimental support for the .yeb easyconfig format is removed][yeb]
76-
77-
---
78-
79-
### Support for Python 2.7 is removed -- Python 3.6+ is required {: #py36 }
80-
81-
EasyBuild 5.0 requires Python >= 3.6 to run.
82-
83-
Running EasyBuild with Python 2.7 or a Python 3 version older than Python 3.6 is no longer supported.
84-
85-
Trying to run EasyBuild with a Python version that is too old will result in an error:
86-
87-
```log
88-
ERROR: No compatible 'python' command found via $PATH (EasyBuild requires Python 3.6+)
89-
```
90-
91-
Python 2.7 has been [end-of-life since 1 Jan 2020](https://www.python.org/doc/sunset-python-2),
92-
and dropping compatibility with Python 2.7 and Python 3.5 enabled some significant code cleanup
93-
(see [easybuild-framework PR #4229](https://github.com/easybuilders/easybuild-framework/pull/4229)).
94-
95-
The [results of the 6th EasyBuild User Survey (2022)](https://easybuild.io/user_survey) show that the impact of
96-
this breaking change on the EasyBuild community should be very limited, since:
97-
98-
* Only ~13% of survey participants were still running EasyBuild on top of Python 2.7;
99-
* No survey participants reported using Python 3.5;
100-
* Over 85% of survey participants reported using Python 3.6, or a more recent version of Python 3;
101-
* Only 3 out of 118 survey participants (~2.5%) reported that dropping support for running EasyBuild
102-
on top of Python 2 would be *problematic* for them;
103-
104-
Along with actively removing code that was only required to retain compatibility with Python 2.7 or 3.5,
105-
the `easybuild.tools.py2vs3` module that was introduced to facilitate supporting both Python 2.7 and Python 3
106-
has been deprecated ([see also below][py2vs3]).
107-
108-
---
109-
110-
### Deprecated EasyBuild bootstrap script is removed {: #bootstrap_script }
111-
112-
The EasyBuild bootstrap script has been removed (see [easybuild-framework PR #4233](https://github.com/easybuilders/easybuild-framework/pull/4233)).
113-
Please see the [installation page][installation] for the suggested methods for installing EasyBuild.
114-
115-
---
116-
117-
### Experimental support for the .yeb easyconfig format is removed {: #yeb }
118-
119-
Support for the experimental `.yeb` easyconfig format has been removed (see [easybuild-framework PR #4237](https://github.com/easybuilders/easybuild-framework/pull/4237)).
120-
This format allowed easyconfigs to be specified in YAML. However, there has been no recent development of this
121-
format and little suggestion that anyone was using it.
122-
123-
---
124-
125-
## Deprecated functionality in EasyBuild v5.0 {: #deprecated_v5 }
126-
127-
Some functionality is being deprecated in EasyBuild v5.0, and will no longer be supported in EasyBuild v6.0:
128-
129-
* [`easybuild.tools.py2vs3` module][py2vs3]
130-
131-
If you trigger any deprecated functionality, a warning message will be printed.
132-
133-
---
134-
135-
### `easybuild.tools.py2vs3` module {: #py2vs3 }
136-
137-
[easybuild-framework PR #4229](https://github.com/easybuilders/easybuild-framework/pull/4229)
138-
139-
The following table lists the changes required to replace imports from the the `py2vs3` module.
140-
141-
| `from easybuild.tools.py2vs3 import ...` | Replacement |
142-
|--|--|
143-
| `ascii_letters` | `from string import ascii_letters` |
144-
| `ascii_lowercase` | `from string import ascii_lowercase` |
145-
| `build_opener` | `from urllib.request import build_opener` |
146-
| `ConfigParser` | `from configparser import ConfigParser` |
147-
| `configparser` | `import configparser` |
148-
| `create_base_metaclass` | `from easybuild.base.wrapper import create_base_metaclass` |
149-
| `extract_method_name` | No import required. Replace `extract_method_name(method)` with `'_'.join(method.__code__.co_names)` |
150-
| `HTMLParser` | `from html.parser import HTMLParser` |
151-
| `HTTPError` | `from urllib.request import HTTPError` |
152-
| `HTTPSHandler` | `from urllib.request import HTTPSHandler` |
153-
| `json_loads` | `from json import loads` and rename `json_loads` to `loads` |
154-
| `Mapping` | `from collections.abc import Mapping` |
155-
| `mk_wrapper_baseclass` | `from easybuild.base.wrapper import mk_wrapper_baseclass` |
156-
| `OrderedDict` | `from collections import OrderedDict` |
157-
| `raise_with_traceback` | No import required. Replace `raise_with_traceback(exception, message, tb)` with `raise exception(message).with_traceback(tb)` |
158-
| `reload` | `from importlib import reload` |
159-
| `Request` | `from urllib.request import Request` |
160-
| `string_type` | No import required. Use `str` directly. |
161-
| `StringIO` | `from io import StringIO` |
162-
| `std_urllib` | `import urllib.request as std_urllib` |
163-
| `subprocess_popen_text` | `from easybuild.tools.run import subprocess_popen_text` |
164-
| `subprocess_terminate` | `from easybuild.tools.run import subprocess_terminate` |
165-
| `urlencode` | `from urllib.parse import urlencode` |
166-
| `URLError` | `from urllib.request import URLError` |
167-
| `urlopen` | `from urllib.request import urlopen` |
28+
This section covers the major planned changes.
16829

30+
It is not intended to be a *complete* list of all changes that are planned for EasyBuild v5.0.

‎docs/easybuild-v5/policies.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Policies related to EasyBuild v5.0
2+
3+
*(for a full overview of changes in EasyBuild v5.0, see [here](overview-of-changes.md))*
4+
5+
Starting with EasyBuild v5.0, we will enforce the new [toolchain support policy](../policies/toolchains.md).

‎docs/easybuild-v5/proposed-changes.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Proposed changes for EasyBuild v5.0
2+
3+
*(for a full overview of changes in EasyBuild v5.0, see [here](overview-of-changes.md))*
4+
5+
There are several proposed changes where the EasyBuild maintainers are seeking community feedback.
6+
If you wish to provide feedback then please comment in the GitHub issue for the proposal.
7+
8+
* [Minimum supported Lmod version](https://github.com/easybuilders/easybuild/issues/871)
9+
* [Toolchain support policy](https://github.com/easybuilders/easybuild/issues/872)

‎docs/easybuild-v5/run_shell_cmd.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# `run_shell_cmd` function
2+
3+
*(for a full overview of changes in EasyBuild v5.0, see [here](overview-of-changes.md))*
4+
5+
In EasyBuild v5.0, a new function named `run_shell_cmd` is introduced to run shell commands.
6+
7+
This function replaces both the `run_cmd` and `run_cmd_qa` functions, which will be deprecated in EasyBuild v5.0.
8+
9+
## Motivation
10+
11+
...
12+
13+
## High-level overview
14+
15+
...
16+
17+
## Use cases
18+
19+
...
20+
21+
## Transitioning from `run_cmd` to `run_shell_cmd`
22+
23+
...
24+
25+
## Transitioning from `run_cmd_qa` to `run_shell_cmd`
26+
27+
...

0 commit comments

Comments
 (0)