You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This page provides information about contributing to Underworld3's (aka Underworld’s) codebase.
2
+
3
+
For contributions of Underworld models or workflows, please see https://github.com/underworld-community
4
+
5
+
----
6
+
7
+
We welcome contributions to Underworld’s codebase in the form of:
8
+
9
+
* Code changes.
10
+
* Bug reports.
11
+
* Suggestions / Requests.
12
+
* Documentation modifications.
13
+
14
+
For Bug reports and Suggestions / Requests please submit an Issue on the Underworld GitHub Issue Tracker. Please tag the Issue with a given Label to help us assess the issue.
15
+
16
+
[Click here](https://github.com/underworldcode/underworld3/issues) to submit an Issue.
17
+
18
+
For Code / Documentation changes please submit a GitHub Pull Request (PR). This allows us to review and discuss the contributions before merging it into our ``development`` branch. For creating Pull Request (PR) we recommend following the workflow outlined on [GitHub](https://guides.github.com/activities/forking).
19
+
20
+
More specifically:
21
+
22
+
1. Fork Underworld via GitHub and clone it to your machine.
2. Add the original Underworld repository as an additional remote source (named `upsteam`) for your local repo and pull down its latest changesets. Checkout to the upstream/development repo state, and then create a new local branch which will contain your forthcoming changes.
3. Make your changes! Remember to write comments, write a testif applicable and follow the [coding style](/docs/developer/CodingStyle.md) of the project for details).
38
+
39
+
4. Push your changes to your GitHub fork and then submit a PR to the ``development`` branch of Underworld via Github.
Copy file name to clipboardExpand all lines: LICENCE.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ top level `README.md` for further information.
5
5
6
6
### Licensing
7
7
8
-
1) All Underworld source code is released under the LGPL-3 (See the file LICENCE in his repository). This covers all files in `underworld` constituting the Underworld3 Python module (library), and any other material not explicitly identified under (2) below.
8
+
1) All Underworld source code is released under the LGPL-3 (See the file LGPLv3.txt in this repository). This covers all files in `underworld` constituting the Underworld3 Python module (library), and any other material not explicitly identified under (2) below.
9
9
10
10
2) Notebooks, stand-alone documentation and Python scripts which show how the code is used and run are licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. We offer this licence to encourage you to modify and share the examples and use them to help you in your research. Where no individual creator is identified in these files, the appropriate attribution is "The Underworld Team". All the files covered by this license are found in the `UserGuide` directory.
Copy file name to clipboardExpand all lines: README.md
+3-2Lines changed: 3 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,8 +8,7 @@ Welcome to `Underworld3`, a mathematically self-describing, finite-element code
8
8
9
9
All `Underworld3` source code is released under the LGPL-3 open source licence. This covers all files in `underworld3` constituting the Underworld3 Python module. Notebooks, stand-alone documentation and Python scripts which show how the code is used and run are licensed under the Creative Commons Attribution 4.0 International License.
[](https://github.com/underworldcode/underworld3/actions/workflows/build_uw3_and_test.yml)
13
12
14
13
## Documentation
15
14
@@ -19,6 +18,8 @@ The `underworld3` module (API) documentation can be found online:
-[Main Branch on Binder](https://mybinder.org/v2/gh/underworld-community/uw3-demo-launcher/HEAD?labpath=underworld3%2Fdocs%2Fuser%2FNotebooks%2FNotebook_Index.ipynb)
Copy file name to clipboardExpand all lines: docs/developer/CodingStyle.md
+14-15Lines changed: 14 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,11 +18,11 @@ def rank2_to_voigt(
18
18
r"""Convert rank 2 tensor ($v_{ij}$) to Voigt (vector) form ($V_I$)"""
19
19
```
20
20
21
-
We do not enforce this formatting at the `git commit` level, but it is strongly encouraged that you set up your code editor to adopt the `black` style.
21
+
We do not enforce this formatting at the `git commit` level, but it is strongly encouraged that you set up your code editor to adopt the `black` style.
22
22
23
23
## Variable / function names
24
24
25
-
Underworld3 leans heavily on the `petsc4py` and `sympy` packages. `petsc4py` wraps the `C` / `Fortran` layers of the `PETSc` ecosystem and tends to inherit CamelCase/camelCase variable naming everywhere whereas `sympy`, like other python packages, *favours* snake_case for variables and CamelCase for classes.
25
+
Underworld3 leans heavily on the `petsc4py` and `sympy` packages. `petsc4py` wraps the `C` / `Fortran` layers of the `PETSc` ecosystem and tends to inherit CamelCase/camelCase variable naming everywhere whereas `sympy`, like other python packages, *favours* snake_case for variables and CamelCase for classes.
26
26
27
27
In Underworld3, we prefer to use snake_case naming for functions, properties and variables, camelCase for classes. We also know that we are not completely consistent at present. Sorry !
28
28
@@ -34,17 +34,17 @@ We use `typing` for this.
34
34
35
35
## Cython considerations
36
36
37
-
Many `underworld3` objects carry underlying `C` objects that they manage and there is usually some `cython` code that handles the interaction between the two. We use `cython` explicitly for some of this wrapper code and it is present implictly because we make heavy use of the `petsc4py` module.
37
+
Many `underworld3` objects carry underlying `C` objects that they manage and there is usually some `cython` code that handles the interaction between the two. We use `cython` explicitly for some of this wrapper code and it is present implictly because we make heavy use of the `petsc4py` module.
38
38
39
39
`cython` objects may require explicit deletion (because python cannot always drill down to the `C` layer to find objects that are ready for automatic deletion). We strongly encourage the use of the `destroy()` method that is available for many `petsc4py` objects when you are sure the object is no longer required by you. Be aware that lists of pointers to `PETSc` objects may prevent them being automatically deleted and use the `weakref` module to avoid this problem.
40
40
41
41
Where possible, keep pure python functions in separate source files from `cython` functions as this improves our ability to run the `pdoc` automatic documentation correctly. Generally speaking, the `cython` level of the API is the furthest from the end-user and the least likely to need continual updating. Let's work to keep this code concise, precise, and rarely changed.
42
42
43
43
## API-level Documentation
44
44
45
-
The best way to develop `Underworld3` python programs is within the [`jupyter`](jupyter.org) notebook environment. The documentation of the `Underworld3` API assumes that rendered markdown formatting will be available for code highlighting and mathematical equations when the user asks (interactively) for help.
45
+
The best way to develop `Underworld3` python programs is within the [`jupyter`](jupyter.org) notebook environment. The documentation of the `Underworld3` API assumes that rendered markdown formatting will be available for code highlighting and mathematical equations when the user asks (interactively) for help.
46
46
47
-
We use `pdoc` to produce API documentation from the python source code. The `pdoc` configuration assumes all docstrings are markdown and may include mathematics and code snippets. `pdoc` automatically documents arguments to functions and classes, so we do not require these to be described unless there is a need for clarification.
47
+
We use `pdoc` to produce API documentation from the python source code. The `pdoc` configuration assumes all docstrings are markdown and may include mathematics and code snippets. `pdoc` automatically documents arguments to functions and classes, so we do not require these to be described unless there is a need for clarification.
48
48
49
49
In the `jupyter` environment `Underworld3` objects display `help` documentation and their internal state through their `self.view()` methods. Many classes have equivalent documentation available before they have been instantiated so a notebook user can progressively construct a model.
50
50
@@ -65,7 +65,7 @@ once the following criteria are met:
The version number may also be appended with pre-release type designations, for
87
87
example 3.0.0b.
88
88
89
-
Development software will be have the 'dev' suffix, e.g. 3.0.0-dev, and should
89
+
Development software will be have the 'dev' suffix, e.g. 3.0.0-dev, and should
90
90
represent the version the development is working towards, so 3.1.0-dev is working
91
-
towards release 3.1.0.
91
+
towards release 3.1.0.
92
92
93
93
## Testing
94
94
95
-
The 'test.sh' script can be used to execute the pytest framework.
95
+
The 'test.sh' script can be used to execute the pytest framework.
96
96
Individual tests are found in the `tests` directory. These are small collections
97
-
of unit tests that address parcels of functionality in the code. Tests need to be
98
-
small and fast, and should be orthogonal to other tests as far as possible.
97
+
of unit tests that address parcels of functionality in the code. Tests need to be
98
+
small and fast, and should be orthogonal to other tests as far as possible.
99
99
In the testing framework, we test the deeper levels of the code first (e.g. mesh building)
100
100
so that we can use those features for subsequent tests.
101
101
102
-
We strongly encourage testing to be fine grained with as little as possible additional code that
103
-
can go wrong. Please do not just paste in your example notebooks in the hope that `pytest` will
104
-
sort things out. It won't. Somebody else will need to figure out why the test broke sometime in the
105
-
future and we don't want that somebody to discover that the problem is not in the unit testing part of the code.
102
+
We strongly encourage testing to be fine grained with as little as possible additional code that can go wrong. Please do not just paste in your example notebooks in the hope that `pytest` will sort things out. It won't. Somebody else will need to figure out why the test broke sometime in the future and we don't want that somebody to discover that the problem is not in the unit testing part of the code.
103
+
104
+
Although `pytest` tests should be independent, there are some issues with the PETSc subsystem removing objects correctly at the end of a test. This is why we break up the testing suite into multiple files which rebuild the PETSc layer each time.
0 commit comments