From f7ebbd14df8087753d12df0c45e3faeb3688f15d Mon Sep 17 00:00:00 2001 From: mferrera Date: Tue, 9 Jan 2024 11:07:44 +0100 Subject: [PATCH] DOC: move Contributing doc to root and update --- CONTRIBUTING.md | 292 ++++++++++++++++++++++++++++++++++++++++++ docs/contributing.rst | 262 +------------------------------------ 2 files changed, 294 insertions(+), 260 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..c9eed1756 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,292 @@ +# Contributing + +Contributions are welcome and greatly appreciated! There are several ways to +contribute to `xtgeo`. + + +## Types of Contributions + + +### Report Bugs + +Report bugs at +[https://github.com/equinor/xtgeo/issues](https://github.com/equinor/xtgeo/issues). + +If you are reporting a bug, please include: + +* Your operating system name and version. +* Any details about your local setup that might be helpful in troubleshooting. +* Detailed steps to reproduce the bug. + + +### Fix Bugs + +Look through the Git issues for bugs. Anything tagged with "bug" +and "help wanted" is open to whoever wants to implement it. + + +### Implement Features + +Look through the Git issues for features. Anything tagged with "enhancement" +and "help wanted" is open to whoever wants to implement it. + + +### Write Documentation + +Yes, `xtgeo` could always use more documentation, whether as part of the +official `xtgeo` docs, in docstrings, or even on the web in blog posts, +articles, and such. + + +### Submit Feedback + +The best way to send feedback is to file an issue at +[https://github.com/equinor/xtgeo/issues](https://github.com/equinor/xtgeo/issues). + +If you are proposing a feature: + +* Explain in detail how it would work. +* Keep the scope as narrow as possible, to make it easier to implement. + + +## Get Started! + +Ready to contribute? Here's how to set up `xtgeo` for local development. + +1. Fork the `xtgeo` repository from the Equinor repository to your GitHub + user account. + +2. Clone your fork locally: + + ```sh + git clone git@github.com:your_name_here/xtgeo + cd xtgeo + git remote add upstream git@github.com:equinor/xtgeo + git remote -v + # origin git@github.com:your_name_here/xtgeo (fetch) + # origin git@github.com:your_name_here/xtgeo (push) + # upstream git@github.com:equinor/xtgeo (fetch) + # upstream git@github.com:equinor/xtgeo (push) + ``` + +3. Install your forked copy into a local venv: + + ```sh + python -m venv ~/venv/xtgeo + source ~/venv/xtgeo/bin/activate + pip install -U pip + pip install -e ".[dev,docs]" # add -vv to see compilation output + ``` + +4. Install the test data one directory below your `xtgeo` directory and run + the tests to ensure everything works: + + ```sh + git clone --depth 1 https://github.com/equinor/xtgeo-testdata ../xtgeo-testdata + pytest -n auto + ``` + +5. Create a branch for local development: + + ```sh + git checkout -b name-of-your-bugfix-or-feature + ``` + + Now you can make your changes locally. + +6. When you're done making changes, check that your changes pass ruff and the + tests: + + ```sh + ruff check . + ruff format . + mypy src/ + pytest tests + ``` + +7. If you want to edit the C/C++ contact the `xtgeo` authors for detailed + instructions. + +8. Commit your changes + (see [Writing commit messages](#writing-commit-messages)) and push your + branch to GitHub: + + ```sh + git add . + git commit -m "ENH: Described changes made" + git push origin name-of-your-bugfix-or-feature + ``` + +9. Submit a pull request through GitHub. + +## Building documentation + +It is a good idea to check that the documentation builds and displays +properly, particularly if you have made changes to it. You can build and look +at the documentation like so: + +```sh +sphinx-build -W -b html docs build/docs/html +``` + +Then open `build/docs/html/index.html` in your browser. + + +## Writing commit messages + +Commit messages should be clear and follow a few basic rules. Example: + +```text +ENH: add functionality X to numpy + +This functionality was added due to a user feature request and relates to +changes X, Y, Z which together completed feature ABC. With this change users +can now do `vals = values.foo().bar()`. +``` + +The first word of the commit message starts with a capitalized acronym +(options listed below) indicating what type of commit this is followed by a +brief description of the change. This line should strive to be less than or +equal to 50 characters. + +More explanation and context is often helpful to developers in the future. If +this is the case you should add a blank link with a longer description giving +some of these contextual details. This commit information can be as long as is +needed but the individual lines shouldn't be longer than 72 characters. + +See [Chris Beams hints on commit messages](https://chris.beams.io/posts/git-commit/) +for more expalanation of these guidelines. + +Describing the motivation for a change, the nature of a bug for bug fixes or +some details on what an enhancement does are also good to include in a commit message. +Messages should be understandable without looking at the code changes. +A commit message like FIX: fix another one is an example of what not to do; +the reader has to go look for context elsewhere. + +Standard acronyms to start the commit message with are: + +```text +API: an (incompatible) API change (will be rare) +BLD: change related to building xtgeo +BUG: bug fix +CI: related to CI/CD workflows +CLN: code cleanup, maintenance commit (refactoring, typos, PEP, etc.) +DEP: deprecate something, or remove a deprecated object +DOC: documentation, addition, updates +ENH: enhancement, new functionality +FIX: fixes wrt to technical issues, e.g. wrong requirements.txt +PERF: performance or bench-marking +REV: revert an earlier commit +REL: related to releasing xtgeo +TST: addition or modification of tests +``` + +### Type Hints + +`xtgeo` requires the use of type annotations in all new feature +developments, incorporating Python 3.10's enhanced syntax for type hints. +This facilitates a more concise and readable style. + + +### Style Guidelines + +- For Python versions prior to 3.10, include the following import for + compatibility: + + ```python + from __future__ import annotations + ``` + +- Use Python's built-in generics (e.g., `list`, `tuple`) directly. This + approach is preferred over importing types like `List` or `Tuple` from + the `typing` module. + +- Apply the new union type syntax using the pipe (`|`) for clarity and + simplicity. For example: + + ```python + primes: list[int | float] = [] + ``` + +- For optional types, use `None` with the pipe (`|`) instead of `Optional`. + For instance: + + ```python + maybe_primes: list[int | None] = [] + ``` + +Note: These guidelines align with PEP 604 and are preferred for all new code +submissions and when updating existing code. + + +## Pull Request Guidelines + +Before you submit a pull request, check that it meets these guidelines: + +1. The pull request should include tests. + +2. If the pull request adds functionality, the docs should be updated. Put + your new functionality into a function with a docstring, and add the + feature to the list in HISTORY.md. + + +## Tips + +- To run a subset of tests, e.g. only surface tests: + + ```python + pytest test/test_surfaces + ``` + +- scikit-build-core offers some suggestions about building with editable + installs, see info here: + + https://scikit-build-core.readthedocs.io/en/latest/configuration.html#editable-installs + + +## Working with RMS python + +The following is a special recipe when working with RMS' Python version, +and it is targeted to Equinor usage using bash shell in Linux: + +```sh +unset PYTHONPATH # to avoid potential issues +# activate RMS python, e.g. RMS version 13.1.2 +source /prog/res/roxapi/aux/roxenvbash 13.1.2 +# make a virtual env (once): +python -m venv ~/venv/py38_rms13.1.2 +source ~/venv/py38_rms13.1.2/bin/activate +python -m pip install -U pip +pip install -e ".[dev]" +pytest +``` + +Now you have an editable install in your virtual environment that can be ran +in RMS while testing. Hence open rms with ``rms`` command (not ``runrms``). + +Inside RMS you can open a Python dialog and run your version of `xtgeo`. Theoretically, +you could now do changes in your editable install and RMS should see them. +However, RMS will not load libraries updates once loaded, and ``importlib.reload`` +will not help very much. One safe alternative is of course to close and +reopen RMS, but that is unpractical and time consuming. + +The better alternative is a brute force hack in order to make it work, +see the five lines of code in top of this example: + +```python +import sys +sysm = sys.modules.copy() +for k, _ in sysm.items(): + if "xtgeo" in k: + del sys.modules[k] + +import xtgeo + +grd = xgeo.grid_from_roxar(project, "Geogrid") +``` + +This will work if you change python code in `xtgeo`. If you change C code in `xtgeo`, then +this hack will not work. The only solution is to close and re-open RMS everytime the +C code is compiled. + + diff --git a/docs/contributing.rst b/docs/contributing.rst index 4616085c8..6889b7c46 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,260 +1,2 @@ -.. highlight:: shell - -============ -Contributing -============ - -Contributions are welcome, and they are greatly appreciated! Every -little bit helps, and credit will always be given. - -You can contribute in many ways: - -Types of Contributions ----------------------- - -Report Bugs -~~~~~~~~~~~ - -Report bugs at https://github.com/equinor/xtgeo/issues. - -If you are reporting a bug, please include: - -* Your operating system name and version. -* Any details about your local setup that might be helpful in troubleshooting. -* Detailed steps to reproduce the bug. - -Fix Bugs -~~~~~~~~ - -Look through the Git issues for bugs. Anything tagged with "bug" -and "help wanted" is open to whoever wants to implement it. - -Implement Features -~~~~~~~~~~~~~~~~~~ - -Look through the Git issues for features. Anything tagged with "enhancement" -and "help wanted" is open to whoever wants to implement it. - -Write Documentation -~~~~~~~~~~~~~~~~~~~ - -Yes, xtgeo could always use more documentation, whether as part of the -official xtgeo docs, in docstrings, or even on the web in blog posts, -articles, and such. - -Submit Feedback -~~~~~~~~~~~~~~~ - -The best way to send feedback is to file an issue -at https://github.com/equinor/xtgeo/issues. - -If you are proposing a feature: - -* Explain in detail how it would work. -* Keep the scope as narrow as possible, to make it easier to implement. - -Get Started! ------------- - -Ready to contribute? Here's how to set up ``xtgeo`` for local development. - -1. Fork the ``xtgeo`` repo on Github equinor to your personal user -2. Clone your fork locally: - -.. code-block:: bash - - $ git clone git@github.com:your_name_here/xtgeo - $ cd xtgeo - $ git remote add upstream git@github.com:equinor/xtgeo - $ git remote -v - origin git@github.com:your_name_here/xtgeo (fetch) - origin git@github.com:your_name_here/xtgeo (push) - upstream git@github.com:equinor/xtgeo (fetch) - upstream git@github.com:equinor/xtgeo (push) - - -3. Install your local copy into a virtualenv. Using python 3, this is how you set -up your fork for local development (first time): - -.. code-block:: bash - - $ mkdir ~/venv/xtgeo; cd ~/venv/xtgeo - $ python -m venv . - $ source bin/activate - $ cd /your_path_to_git_clone/xtgeo/ - $ pip install pip -U - $ pip install ".[dev,docs]" - $ pytest # to check that stuff works - -4. Create a branch for local development: - -.. code-block:: bash - - $ git checkout -b name-of-your-bugfix-or-feature - -Now you can make your changes locally. - -5. When you're done making changes, check that your changes pass ruff and the tests: - -.. code-block:: bash - - $ ruff check . - $ pytest tests - -6. If you want to edit C code, take contact with the author for detailed instructions. - - -7. Commit your changes (see below) and push your branch to GitHub: - -.. code-block:: bash - - $ git add . - $ git commit -m "AAA: Your detailed description of your changes." - $ git push origin name-of-your-bugfix-or-feature - -8. Submit a pull request through the Github website. - - -Working with RMS python ------------------------ -The following is a special recipe when working with RMS' python version, -and it is targeted to Equinor usage using bash shell in Linux: - -.. code-block:: bash - - $ unset PYTHONPATH # to avoid potential issues - # activate RMS python, e.g. RMS version 12.0.2 - $ source /project/res/roxapi/aux/roxenvbash 12.0.2 - # make a virtual env (once): - $ python -m venv ~/venv/py36_rms12.0.2 - $ source ~/venv/py36_rms12.0.2/bin/activate - $ cd path_to_xtgeo/ - $ python -m pip install pip -U - $ pip install ".[dev]" - $ pytest - -Now you have an editable install in your virtual environment that can be ran -in RMS while testing. Hence open rms with ``rms`` command (not ``runrms``). - -Inside RMS you can open a Python dialog and run your version of xtgeo. Theoretically, -you could now do changes in your editable install and RMS should see them. -However, RMS will not load libraries updates once loaded, and ``importlib.reload`` -will not help very much. One safe alternative is of course to close and -reopen RMS, but that is unpractical and time consuming. -The better alternative is a brute force hack in order to make it work, -see the five lines of code in top of this example: - -.. code-block:: python - - import sys - sysm = sys.modules.copy() - for k, _ in sysm.items(): - if "xtgeo" in k: - del sys.modules[k] - - import xtgeo - - grd = xgeo.grid_from_roxar(project, "Geogrid") - -This will work if you change python code in xtgeo. If you change C code in xtgeo, then -this hack will not work. The only solution is to close and re-open RMS everytime the -C code is compiled. - -Writing commit messages ------------------------ -The following takes effect from year 2021. - -Commit messages should be clear and follow a few basic rules. Example: - -.. code-block:: text - - ENH: add functionality X to numpy.. - -The first line of the commit message starts with a capitalized acronym -(options listed below) indicating what type of commit this is. Then a blank -line, then more text if needed. Lines shouldn't be longer than 72 -characters. If the commit is related to a ticket, indicate that with -``"See #3456", "Cf. #3344, "See ticket 3456", "Closes #3456"`` or similar. - -Read `Chris Beams hints on commit messages `_. - -Describing the motivation for a change, the nature of a bug for bug fixes or -some details on what an enhancement does are also good to include in a commit message. -Messages should be understandable without looking at the code changes. -A commit message like FIX: fix another one is an example of what not to do; -the reader has to go look for context elsewhere. - -Standard acronyms to start the commit message with are: - -.. code-block:: text - - API: an (incompatible) API change (will be rare) - PERF: performance or bench-marking - BLD: change related to building xtgeo - BUG: bug fix - FIX: fixes wrt to technical issues, e.g. wrong requirements.txt - DEP: deprecate something, or remove a deprecated object - DOC: documentation, addition, updates - ENH: enhancement, new functionality - CLN: code cleanup, maintenance commit (refactoring, typos, PEP, etc.) - REV: revert an earlier commit - TST: addition or modification of tests - REL: related to releasing xtgeo - -Type Hints ----------- - -As of 2023, xtgeo requires the use of type annotations in all new feature -developments, incorporating Python 3.10's enhanced syntax for type hints. -This facilitates a more concise and readable style. - -Style Guidelines -~~~~~~~~~~~~~~~~ - -- For Python versions prior to 3.10, include the following import for compatibility: - - .. code-block:: python - - from __future__ import annotations - -- Use Python's built-in generics (e.g., `list`, `tuple`) directly. This approach is preferred over importing types like `List` or `Tuple` from the `typing` module. - -- Apply the new union type syntax using the pipe (`|`) for clarity and simplicity. For example: - - .. code-block:: python - - primes: list[int | float] = [] - -- For optional types, use `None` with the pipe (`|`) instead of `Optional`. For instance: - - .. code-block:: python - - maybe_primes: list[int | None] = [] - -Note: These guidelines align with PEP 604 and are preferred for all new code submissions and when -updating existing code. - - -Pull Request Guidelines ------------------------ - -Before you submit a pull request, check that it meets these guidelines: - -1. The pull request should include tests. -2. If the pull request adds functionality, the docs should be updated. Put - your new functionality into a function with a docstring, and add the - feature to the list in HISTORY.md. - - -Tips ----- - -- To run a subset of tests, e.g. only surface tests: - -.. code:: bash - - $ pytest test/test_surfaces - -- scikit-build-core offers some suggestions about building with editable installs, se info here: - -https://scikit-build-core.readthedocs.io/en/latest/configuration.html#editable-installs +.. include:: ../CONTRIBUTING.md + :parser: myst_parser.sphinx_