diff --git a/CHANGELOG.md b/CHANGELOG.md index 65680407..9839ade3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 PR [#247](https://github.com/fabric-testbed/fabrictestbed-extensions/pull/247)) - Version in pyproject.toml (Issue [#248](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/248)) +- Separate contribution guidelines (Issue + [#242](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/242), + [#243](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/243), + PR [#251](https://github.com/fabric-testbed/fabrictestbed-extensions/pull/251)) ## [1.5.5] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..2d531678 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,163 @@ +# Contributing to FABlib + +Thank you for considering to help FABlib! We welcome contributions in +the form of bug reports, feature requests, code patches, documentation +updates, and anything else that may be helpful. Please review these +guidelines first. + +FABlib is developed on its GitHub [repository], and uses GitHub issues +and pull requests. + + +## Submitting Issues + +If you want to add a new feature to FABlib or report that something is +broken, please submit an issue via GitHub. If you find a bug, please +describe it in enough detail so that we can quickly reproduce them. + + +## Submitting Pull Requests + +Contributions to FABlib are made with GitHub Pull Requests. When you +submit a pull request, some tests will run against it: + +- Code formatting will be checked using [black] and [isort]. Be sure + that your code is formatted with these tools. +- FABRIC project has a policy of requiring GPG signed commits. + Commits on the PR branch will be checked to ensure that they are + signed. +- `CHANGELOG.md` will be checked for updates. +- Unit tests will be run. +- Packages will be built. + +Most of these checks must pass before a PR is approved and merged. We +do not tend to be excessively strict about enforcing these checks, +except the one that checks for signed commits. Signed commits are +mandatory. + + +## Testing FABlib + +FABlib currently has a modest set of unit and integration tests, under +[tests] directory. Install [tox] to run them in isolated virtual +environments: + +```console +$ pip install tox +``` + +Unit tests can be run like so: + +```console +$ tox +``` + +Integration tests can be run like so: + +```console +$ tox -e integration +``` + +If you want to run some tests directly using [pytest], that is +possible too: + +``` +$ pip install -e .[test] +$ pytest -s tests/integration/test_hello_fabric.py +``` + +## Documenting FABlib + +FABlib uses Sphinx to generate API documentation from Python +docstrings. Publishing them at [Read the Docs][fablib-api-rtd] is a +mostly automated process. + +When working on API documentation on your local setup, in order to +preview the generated HTML, run: + +``` +$ tox -e docs +``` + +Resulting files can be found in `docs/build/html/`. + + +## Packaging FABlib + +FABlib uses [flit] as the build backend. To build source and wheel +packages, do this: + +```console +$ pip install flit +$ flit build +``` + +While using flit as the build backend, continuing to use [build] as +the build frontend should work too: + +``` +$ pip install build +$ python -m build +``` + + +## Releasing FABlib + +The "[publish]" workflow automates building packages and publishing +them on PyPI. In order to publish a new FABlib version on PyPI, +follow these steps: + +1. Bump up version in `pyproject.toml`. +2. Update `CHANGELOG.md`. +3. Start a PR with these changes, and get it merged. +4. Once the PR is merged, do: `git switch main; git pull main` +5. Tag the release, and push the tag to GitHub: + + ```console + $ git tag --sign --message="Great set of features" + $ git push --tags + ``` +This should trigger the publish workflow that will: + +- Run unit tests, +- Build FABlib sdist and wheel packages, +- Publish the packages on PyPI, and +- Create a GitHub release. + + +### Manual steps + +In order to "manually" upload FABlib packages (such as in the case of +release candidate versions), bump up the version string in the +appropriate place, and then do: + +```console +$ flit publish +``` + +Continuing to use twine to publish packages is an option too: + +```console +$ twine upload dist/* +``` + +For details about publishing to PyPI, see flit documentation about +[package uploads]. + + + + +[repository]: https://github.com/fabric-testbed/fabrictestbed-extensions/ + +[flit]: https://flit.pypa.io/en/stable/ +[package uploads]: https://flit.pypa.io/en/latest/upload.html + +[build]: https://pypi.org/project/build/ +[tox]: https://pypi.org/project/tox/ +[pytest]: https://pypi.org/project/pytest/ +[black]: https://pypi.org/project/black/ +[isort]: https://pypi.org/project/isort/ + +[tests]: ./tests/ + +[publish]: ./.github/workflows/publish.yml diff --git a/README.md b/README.md index cf9f9dbd..ed4646f1 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,23 @@ [![pypi-badge]][pypy] [![api-docs-badge]][api-docs] -This repository contains implementation of a Python API, otherwise -known as "FABlib", for intereacting with [FABRIC][fabric] testbed. +This is the implementation of a Python library, otherwise known as +"FABlib", for intereacting with [FABRIC][fabric] testbed. +Your first encounter with FABlib might be through FABRIC project's +[JupyterHub instance][fabric-jupyter], where FABlib is pre-installed +for you. You will be presented with many examples of interacting with +FABRIC testbed and FABlib usage when you log in there. Those [notebook +sources][fabric-jupyter-examples] can be found on GitHub as well. + +If you want to interact with FABRIC from Jupyter or a Python project +on your local development environment, that is possible too. See +[Install the FABRIC Python API][fablib-install] and the notes below +for details. + +FABlib API docs can be found [here][fablib-api-rtd]. If you have +questions about FABRIC or FABlib usage, please ask them in FABRIC +[forums]. ## Installing FABlib @@ -42,140 +56,27 @@ except Exception as e: print(f"Exception: {e}") ``` -Your first encounter with FABlib however might be through FABRIC -project's [JupyterHub][fabric-jupyter] instance. You will be presented -with many examples on FABlib usage when you log in there. The -[notebook sources][fabric-jupyter-examples] can be found on GitHub as -well. - -Since FABlib 1.4, API docs can be found [here][fablib-api-rtd]. Older -API docs are [here][fablib-api-old]. - -If you want to interact with FABRIC from Jupyter installed on your -computer, see: [Install the FABRIC Python API][fablib-install]. - +Please note that some [configuration] is required for this to work. ## Contributing to FABlib -Contributions to FABlib are made with GitHub Pull Requests. When you -submit a pull request, some tests will run against it: - -- Code formatting will be checked using [black] and [isort]. Be sure - that your code is formatted with these tools. -- Unit tests will be run. -- Packages will be built. -- CHANGELOG.md will be checked for updates. - - -## Testing FABlib - -FABlib currently has a modest set of unit and integration tests, under -the top-level `tests` directory. Unit tests can be run like so, using -[tox]: - -```console -$ pip install tox -$ tox -``` - -Integration tests can be run like so: - -```console -$ tox -e integration -``` - -Tox attempts to run tests in an isolated virtual environment. If you -want to run some tests directly using [pytest], that is possible too: - -``` -$ pip install -e .[test] -$ pytest -s tests/integration/test_hello_fabric.py -``` - -## Documenting FABlib - -FABlib uses Sphinx to generate API documentation from Python -docstrings. Publishing them at [Read the Docs][fablib-api-rtd] is a -mostly automated process. - -When working on API documentation on your local setup, in order to -preview the generated HTML, run: - -``` -$ tox -e docs -``` - -Resulting files can be found in `docs/build/html/`. - - -## Packaging FABlib - -FABlib uses [flit] as the build backend. To build source and wheel -packages, do this: - -```console -$ pip install flit -$ flit build -``` - -While using flit as the build backend, continuing to use [build] as -the build frontend should work too: - -``` -$ pip install build -$ python -m build -``` - - -## Releasing FABlib - -The "[publish]" workflow automates building packages and publishing -them on PyPI. In order to publish a new FABlib version on PyPI, -follow these steps: - -1. Bump up version in `pyproject.toml`. -2. Update `CHANGELOG.md`. -3. Start a PR with these changes, and get it merged. -4. Tag the release, and push the tag to GitHub: - - ```console - $ git tag --sign --message="Great set of features" relX.Y.Z - $ git push --tags relX.Y.Z - ``` -This should trigger the publish workflow that will: (1) run unit -tests, (2) build FABlib sdist and wheel packages, (3) publish -the packages on PyPI, and (4) create a GitHub release. - - -### Manual steps - -In order to "manually" upload FABlib packages (such as in the case of -release candidate versions), bump up the version string in the -appropriate place, and then do: - -```console -$ flit publish -``` - -Continuing to use twine to publish packages is an option too: - -```console -$ twine upload dist/* -``` - -For details about publishing to PyPI, see flit documentation about -[package uploads]. +We welcome contributions in the form of bug reports, feature requests, +code patches, documentation updates, etc. If you have ideas that can +help FABlib, please review the [guidelines] first. [pypy]: https://pypi.org/project/fabrictestbed-extensions/ -[pypi-badge]: https://img.shields.io/pypi/v/fabrictestbed-extensions?style=plastic (PyPI) +[pypi-badge]: https://img.shields.io/pypi/v/fabrictestbed-extensions (PyPI) [api-docs]: https://fabric-fablib.readthedocs.io/en/latest/?badge=latest [api-docs-badge]: https://readthedocs.org/projects/fabric-fablib/badge/?version=latest (Documentation Status) [fabric]: https://fabric-testbed.net/ +[forums]: https://learn.fabric-testbed.net/forums/ + +[fablib-api-rtd]: https://fabric-fablib.readthedocs.io/en/latest/ [venv]: https://docs.python.org/3/library/venv.html [virtualenv]: https://virtualenv.pypa.io/en/latest/ @@ -185,16 +86,6 @@ For details about publishing to PyPI, see flit documentation about [fabric-jupyter-examples]: https://github.com/fabric-testbed/jupyter-examples [fablib-install]: https://learn.fabric-testbed.net/knowledge-base/install-the-python-api/ -[fablib-api-rtd]: https://fabric-fablib.readthedocs.io/en/latest/ -[fablib-api-old]: https://learn.fabric-testbed.net/docs/fablib/fablib.html - -[flit]: https://flit.pypa.io/en/stable/ -[package uploads]: https://flit.pypa.io/en/latest/upload.html - -[build]: https://pypi.org/project/build/ -[tox]: https://pypi.org/project/tox/ -[pytest]: https://pypi.org/project/pytest/ -[black]: https://pypi.org/project/black/ -[isort]: https://pypi.org/project/isort/ +[configuration]: https://fabric-fablib.readthedocs.io/en/latest/#configuring-fablib -[publish]: ./.github/workflows/publish.yml +[guidelines]: ./CONTRIBUTING.md