Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Release v0.18.3 #131

Merged
merged 4 commits into from
Dec 4, 2024
Merged

Release v0.18.3 #131

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e923fc9
chore: bump version refs to `0.18.3`
sr-murthy Dec 3, 2024
fa9e61a
docs: simplify the Getting Started docs + tidy up here and there
sr-murthy Dec 3, 2024
601da42
chore(deps): update all dev. deps
sr-murthy Dec 3, 2024
d1c3bc7
docs: fix RST typo in Getting Started source
sr-murthy Dec 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CITATION.cff
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,5 +24,5 @@ keywords:
- real numbers

license: MPL-2.0
version: 0.18.2
date-released: 2024-11-12
version: 0.18.3
date-released: 2024-12-04
149 changes: 35 additions & 114 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,39 +3,25 @@ google-site-verification

# Contributing

Contributors and contributions are welcome. Please read these guidelines
first.
Contributors and contributions are welcome. Please read these guidelines first.

## Git

The project homepage is on
[GitHub](https://github.com/sr-murthy/continuedfractions).
The project homepage is on [GitHub](https://github.com/sr-murthy/continuedfractions).

Contributors can open pull requests from a fork targeting the parent
`main`
[branch](https://github.com/sr-murthy/continuedfractions/tree/main). But
it may be a good first step to create an
[issue](https://github.com/sr-murthy/continuedfractions/issues) or open
a [discussion
topic](https://github.com/sr-murthy/continuedfractions/discussions).
Contributors can open pull requests from a fork targeting the parent `main` [branch](https://github.com/sr-murthy/continuedfractions/tree/main). But it may be a good first step to create an [issue](https://github.com/sr-murthy/continuedfractions/issues) or open a [discussion topic](https://github.com/sr-murthy/continuedfractions/discussions).

A simple Git workflow, using a feature and/or fix branch created off the
`main` branch of your fork, is recommended.
A simple Git workflow, using a feature and/or fix branch created off the `main` branch of your fork, is recommended.

## Repo

If you wish to contribute please first ensure you have [SSH access to
GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh).
This basically involves creating a project-specific SSH keypair - if you
don't already have one - and adding it to GitHub. If you have done this
successfully then this verification step should work:
If you wish to contribute please first ensure you have [SSH access to GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh). This basically involves creating a project-specific SSH keypair - if you don't already have one - and adding it to GitHub. If you have done this successfully then this verification step should work:

``` shell
ssh -vT [email protected]
```

Some SSH configuration may be required: on MacOS or Linux your
user-defined SSH configuration file (`~/.ssh/config`) should look
Some SSH configuration may be required: on MacOS or Linux your user-defined SSH configuration file (`~/.ssh/config`) should look
something like this:

``` shell
Expand All @@ -48,30 +34,19 @@ Host github.com
PasswordAuthentication no
```

For Windows please consult the [Windows OpenSSH
documentation](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_server_configuration).
For Windows please consult the [Windows OpenSSH documentation](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_server_configuration).

Once you’ve forked the repository, you can clone your fork, e.g. over
SSH:
Once you’ve forked the repository, you can clone your fork, e.g. over SSH:

``` python
git clone git+ssh://[email protected]/<fork user>/continuedfractions
```

You can create additional remotes for the parent project to enable
easier syncing, or you can simply create PRs directly against the parent
project.
You can create additional remotes for the parent project to enable easier syncing, or you can simply create PRs directly against the parent project.

## Dependencies & PDM

The package has no external (production) dependencies - some development
dependencies are specified in the `[tool.pdm.dev-dependencies]` section
of the [project
TOML](https://github.com/sr-murthy/continuedfractions/blob/main/pyproject.toml),
but they are not mandatory. Of these, the most important are probably
the `'test'` dependencies, including
[pytest](https://docs.pytest.org/en/8.0.x/) and
[pytest-cov](https://pytest-cov.readthedocs.io/):
The package has no external (production) dependencies - some development dependencies are specified in the `[tool.pdm.dev-dependencies]` section of the [project TOML](https://github.com/sr-murthy/continuedfractions/blob/main/pyproject.toml), but they are not mandatory. Of these, the most important are probably the `'test'` dependencies, including [pytest](https://docs.pytest.org/en/8.0.x/) and [pytest-cov](https://pytest-cov.readthedocs.io/):

``` toml
test = [
Expand All @@ -82,128 +57,82 @@ test = [
]
```

[PDM](https://pdm-project.org/latest) is used (by myself, currently, the
sole maintainer) to manage all dependencies and publish packages to
PyPI. It is also used to automate certain tasks, such as running tests,
as described in the section.
[PDM](https://pdm-project.org/latest) is used (by myself, currently, the sole maintainer) to manage all dependencies and publish packages to PyPI. It is also used to automate certain tasks, such as running tests, as described in the section.

There are no root-level `requirements*.txt` files - but only a single
(default, version-controlled, cross-platform)
[pdm.lock](https://github.com/sr-murthy/continuedfractions/blob/main/pdm.lock)
lockfile, which defines metadata for all TOML-defined development
dependencies, including the currently empty set of production
dependencies, and their sub-dependencies etc. This can be used to
install all development dependencies, including the project itself, in
editable mode where available:
There are no root-level `requirements*.txt` files - but only a single (default, version-controlled, cross-platform)
[pdm.lock](https://github.com/sr-murthy/continuedfractions/blob/main/pdm.lock) lockfile, which defines metadata for all TOML-defined development dependencies, including the currently empty set of production dependencies, and their sub-dependencies etc. This can be used to install all development dependencies, including the project itself, in editable mode where available:

``` shell
pdm install -v --dev
```

> [!NOTE]
> It is important to note that `pdm install` uses either the default
> lockfile (`pdm.lock`), or one specified with `-L <lockfile>`. Multiple
> lockfiles can be generated and maintained. Refer to the [PDM install
> documentation](https://pdm-project.org/latest/reference/cli/#install)
> for more information.
> It is important to note that `pdm install` uses either the default lockfile (`pdm.lock`), or one specified with `-L <lockfile>`. Multiple lockfiles can be generated and maintained. Refer to the [PDM install documentation](https://pdm-project.org/latest/reference/cli/#install) for more information.

If you don't wish to install any editable dependencies, including the
project itself, you can use:
If you don't wish to install any editable dependencies, including the project itself, you can use:

``` shell
pdm install -v --dev --no-editable --no-self
```

The default lockfile can be updated with any and all upstream changes in
the TOML-defined dependencies, but excluding any editable dependencies
including the project itself, using:
The default lockfile can be updated with any and all upstream changes in the TOML-defined dependencies, but excluding any editable dependencies including the project itself, using:

``` shell
pdm update -v --dev --no-editable --no-self --update-all
```

This will usually modify `pdm.lock`, in which case the file should be
staged and included in a commit.
This will usually modify `pdm.lock`, in which case the file should be staged and included in a commit.

The lockfile can be exported in its entirety to another format, such as
`docs/requirements.txt` using:
The lockfile can be exported in its entirety to another format, such as `docs/requirements.txt` using:

``` shell
pdm export -v -f requirements --dev -o docs/requirements.txt
```

For more information on PDM lockfiles and installing requirements see
the [PDM documentation](https://pdm-project.org/latest/).
For more information on PDM lockfiles and installing requirements see the [PDM documentation](https://pdm-project.org/latest/).

## Tests `microscope`

Tests are defined in the `tests` folder, and should be run with
[pytest](https://pytest-cov.readthedocs.io/en/latest/).
Tests are defined in the `tests` folder, and should be run with [pytest](https://pytest-cov.readthedocs.io/en/latest/).

For convenience different types of test targets are defined in the
[Makefile](https://github.com/sr-murthy/continuedfractions/blob/main/Makefile):
`lint` for Ruff linting, `doctests` for running
[doctests](https://docs.python.org/3/library/doctest.html) and
`unittests` for running unittests and measuring coverage, using `pytest`
and the `pytest-cov` plugin:
For convenience different types of test targets are defined in the [Makefile](https://github.com/sr-murthy/continuedfractions/blob/main/Makefile): `lint` for Ruff linting, `doctests` for running [doctests](https://docs.python.org/3/library/doctest.html) and
`unittests` for running unittests and measuring coverage, using `pytest` and the `pytest-cov` plugin:

``` shell
make lint
make unittests
make doctests
```

Linting warnings should be addressed first, and any changes staged and
committed.
Linting warnings should be addressed first, and any changes staged and committed.

Unit tests can be run all at once using `make unittests` or individually
using `pytest`, e.g. running the test class for the
Unit tests can be run all at once using `make unittests` or individually using `pytest`, e.g. running the test class for the
`~continuedfractions.lib.continued_fraction_rational` function:

``` shell
python -m pytest -sv tests/units/test_lib.py::TestContinuedFractionRational
```

> [!NOTE]
> The `-s` option in the `pytest` command is to allow interactive
> environments to be entered on errors, e.g. debugger breakpoints. The
> default behaviour of [capturing console
> input/output](https://docs.pytest.org/en/stable/how-to/capture-stdout-stderr.html#default-stdout-stderr-stdin-capturing-behaviour)
> would otherwise prevent debuggers from being triggered.

The doctests serve as acceptance tests, and are best run after the unit
tests. They can be run all at once using `make doctests`, or
individually by library using `python -m doctest`, e.g. running all the
doctests in `~continuedfractions.sequences`:
The doctests serve as acceptance tests, and are best run after the unit tests. They can be run all at once using `make doctests`, or individually by library using `python -m doctest`, e.g. running all the doctests in `~continuedfractions.sequences`:

``` shell
python -m doctest -v src/continuedfractions/sequences.py
```

## Documentation

[Project
documentation](https://continuedfractions.readthedocs.io/en/latest/) is
defined and built using [Sphinx](https://www.sphinx-doc.org/en/master/),
and deployed to [Read The Docs](https://readthedocs.org). Currently, the
building and deployment steps for documentation are not automated in a
CI pipeline, but are done manually - this will be addressed in future
[Project documentation](https://continuedfractions.readthedocs.io/en/latest/) is defined and built using [Sphinx](https://www.sphinx-doc.org/en/master/), and deployed to [Read The Docs](https://readthedocs.org). Currently, the building and deployment steps for documentation are not automated in a CI pipeline, but are done manually - this will be addressed in future
releases.

The Sphinx documentation source pages and assets are contained in the
`docs/` subfolder. The HTML pages can be built locally on any branch
(from the project root) using:
The Sphinx documentation source pages and assets are contained in the `docs/` subfolder. The HTML pages can be built locally on any branch (from the project root) using:

``` shell
make -C docs html
```

The pages will be built inside `docs/html`, with the index/home page
being `docs/html/index.html`.
The pages will be built inside `docs/html`, with the index/home page being `docs/html/index.html`.

In order for this to work first ensure that you have installed the
documentation Python requirements listed in `docs/requirements.txt`.
This can be done either via `pip`:
In order for this to work first ensure that you have installed the documentation Python requirements listed in `docs/requirements.txt`. This can be done either via `pip`:

``` shell
pip install -r docs/requirements.txt
Expand All @@ -217,23 +146,15 @@ pdm install -v --dev --no-editable --no-self

## CI

The CI pipelines are defined in the [CI
YML](https://github.com/sr-murthy/continuedfractions/blob/main/.github/workflows/ci.yml)
and the [CodeQL Analysis
YML](https://github.com/sr-murthy/continuedfractions/blob/main/.github/workflows/codeql-analysis.yml).
Currently, pipelines for all branches include a tests stage that
includes Ruff linting, unit tests, Python doctests, and in that order.
The CI pipelines are defined in the [CI YML](https://github.com/sr-murthy/continuedfractions/blob/main/.github/workflows/ci.yml)
and the [CodeQL Analysis YML](https://github.com/sr-murthy/continuedfractions/blob/main/.github/workflows/codeql-analysis.yml).
Currently, pipelines for all branches include a tests stage that includes Ruff linting, unit tests, Python doctests, and in that order.

## Versioning and Releases

The [PyPI package](https://pypi.org/project/continuedfractions/) is
currently at version `0.18.2` - the goal is to use [semantic
versioning](https://semver.org/) consistently for all future releases,
but some earlier releases do not comply with strict semantic versioning.
The [PyPI package](https://pypi.org/project/continuedfractions/) is currently at version `0.18.3` - the goal is to use [semantic
versioning](https://semver.org/) consistently for all future releases, but some earlier releases do not comply with strict semantic versioning.

There is currently no dedicated pipeline for releases - both [GitHub
releases](https://github.com/sr-murthy/continuedfractions/releases) and
[PyPI packages](https://pypi.org/project/continuedfractions) are
published manually, but both have the same version tag.
There is currently no dedicated pipeline for releases - both [GitHub releases](https://github.com/sr-murthy/continuedfractions/releases) and [PyPI packages](https://pypi.org/project/continuedfractions) are published manually, but both have the same version tag.

Pipelines for releases will be added as part of a future release.
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@

A simple extension of the Python [`fractions`](https://docs.python.org/3/library/fractions.html) standard library for working with (finite, simple) [continued fractions](https://en.wikipedia.org/wiki/Continued_fraction) as Python objects.

The [package](https://pypi.org/project/continuedfractions/) is updated as necessary with improvements, features and fixes. Only standard libraries are used, and the package is supported on **Python 3.10**, **3.11**, **3.12** and **3.13**.
This is a [PyPI package](https://pypi.org/project/continuedfractions/). It is updated as necessary with improvements, features and fixes. Only standard libraries are used, and the package is tested on **Python 3.10-3.13**, although it should be compatible with many earlier versions as well.
```shell
pip install -U continuedfractions
```
Expand Down
Loading
Loading