diff options
Diffstat (limited to '.github/CONTRIBUTING.md')
| -rw-r--r-- | .github/CONTRIBUTING.md | 55 |
1 files changed, 28 insertions, 27 deletions
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 5ee2d93..9d4065f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -6,33 +6,38 @@ the Python coding style conventions (i.e., [PEP 8](https://www.python.org/dev/pe closely. Additionally, we really want comprehensive docstrings that follow [PEP 257](https://www.python.org/dev/peps/pep-0257/) using the [numpydoc style](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard), -usable offline documentation, and good unit tests for the pytest framework. A +usable offline documentation, and good unit tests for the ``pytest`` framework. A good contribution includes all of these. To ensure compliance with our coding style, we make use of the [pre-commit](https://pre-commit.com/) framework to run several *hooks* when committing code. Please follow the instructions below if you intend to contribute to the lmfit repository: -- clone the GitHub repository: - ``git clone https://github.com/lmfit/lmfit-py.git`` +- fork the GitHub repository +- clone your forked GitHub repository: + ``git clone https://github.com/<your-name>/lmfit-py.git`` - install all (optional) dependencies either using ``pip`` or ``conda``: - ``pip -r install requirements-dev.txt`` or - ``conda install <packages in requirements-dev.txt>`` -- initialize ``pre-commit`` running ``pre-commit install`` in the lmfit directory + ``pip install lmfit[all]`` or + ``conda install <all packages listed in setup.cfg>`` +- initialize ``pre-commit`` by running ``pre-commit install`` in the lmfit directory - create a new branch: ``git checkout -b <awesome_new_feature>`` - start coding +- install the latest version of your code using the PEP517/PEP518 way (``python -m build && pip install .``) - make sure the test-suite passes locally: run ``pytest`` in the lmfit directory +- make sure the documentation builds locally: run ``make`` in the doc directory - push to your fork: ``git push origin`` -- open a Pull Request on https://github.com/lmfit/lmfit-py/pulls +- open a Pull Request on [the lmfit GitHub repository](https://github.com/lmfit/lmfit-py/pulls) If you need any additional help, please send a message to the -[mailing list](https://groups.google.com/group/lmfit-py)! - +[mailing list](https://groups.google.com/group/lmfit-py) or use the +[GitHub discussions page](https://github.com/lmfit/lmfit-py/discussions). ## Using the Mailing List versus GitHub Issues -If you have ***questions, comments, or suggestions*** for lmfit, please use the -[mailing list](https://groups.google.com/group/lmfit-py). This provides an -online conversation that is archived and can be searched easily. +If you have ***questions, comments, or suggestions*** for lmfit, please use +the [mailing list](https://groups.google.com/group/lmfit-py) or +[GitHub discussions page](https://github.com/lmfit/lmfit-py/discussions). +These provide online conversations that are archived and can be searched +easily. If you find a ***bug with the code or documentation***, please use [GitHub Issues](https://github.com/lmfit/lmfit-py/issues) to submit a bug report. @@ -40,16 +45,15 @@ If you have an idea for how to solve the problem and are familiar with Python and GitHub, submitting a [Pull Request](https://github.com/lmfit/lmfit-py/pulls) would be greatly appreciated (see above). -**If you are at all unsure whether to use the mailing list or open an Issue, -please start a conversation on the mailing list.** - -Starting the conversation with "How do I do this?" or "Why didn't this work?" -instead of "This doesn't work" is preferred, and will better help others with -similar questions. No posting about fitting data is inappropriate for the -mailing list, but many questions are not Issues. We will try our best to engage -in all discussions, but we may simply close GitHub Issues that are actually -questions. +**If you are at all unsure whether to open an Issue, please start a +conversation on the discussions page or mailing list.** +Starting the conversation with "How do I do this?" or "Why didn't this work +the way I expected?" instead of "This doesn't work" is preferred, and will +better help others with similar questions. No posting about fitting data is +inappropriate for the mailing list, but many questions are not Issues. We +will try our best to engage in all discussions, but we may simply close +GitHub Issues that are actually questions. ## Providing an Example with GitHub Issues @@ -72,13 +76,11 @@ version and installed dependencies. You can paste the code below in your Python shell to get this information: ```python -import sys, lmfit, numpy, scipy, asteval, uncertainties, six -print('Python: {}\n\nlmfit: {}, scipy: {}, numpy: {}, asteval: {}, uncertainties: {}, six: {}'\ - .format(sys.version, lmfit.__version__, scipy.__version__, numpy.__version__, \ - asteval.__version__, uncertainties.__version__, six.__version__)) +import sys, lmfit, numpy, scipy, asteval, uncertainties +print(f"Python: {sys.version}\n\nlmfit: {lmfit.__version__}, scipy: {scipy.__version__}, numpy: {numpy.__version__}," + f"asteval: {asteval.__version__}, uncertainties: {uncertainties.__version__}") ``` - ## Using IPython Notebooks to Show Examples IPython Notebooks are very useful for showing code snippets and outcomes, @@ -86,7 +88,6 @@ and are a good way to demonstrate a question or raise an issue. Please see the above about providing examples. The notebook you provide will be *read*, but will probably not be run. - ## Secret Code for First Time Issues If you have not done so in the past, and are going to submit a GitHub Issue, |