https://github.com/saransh-cpp/releaseup
An extractive approach for generating release notes from comments and docstrings.
https://github.com/saransh-cpp/releaseup
Last synced: 11 months ago
JSON representation
An extractive approach for generating release notes from comments and docstrings.
- Host: GitHub
- URL: https://github.com/saransh-cpp/releaseup
- Owner: Saransh-cpp
- License: mit
- Created: 2022-09-15T10:33:27.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-07T11:59:37.000Z (over 1 year ago)
- Last Synced: 2025-06-20T10:58:33.013Z (12 months ago)
- Language: Python
- Homepage: https://releaseup.readthedocs.io/
- Size: 165 KB
- Stars: 11
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# releaseup
[](https://github.com/Saransh-cpp/releaseup/actions/workflows/ci.yml)
[](https://releaseup.readthedocs.io/en/latest/?badge=latest)
[](https://results.pre-commit.ci/latest/github/Saransh-cpp/releaseup/main)
[](https://codecov.io/gh/Saransh-cpp/releaseup)
[](https://github.com/Saransh-cpp/releaseup/discussions)
[](https://pypi.org/project/releaseup/)
[](https://pypi.org/project/releaseup/)
[](https://pepy.tech/project/releaseup)
[](https://github.com/psf/black)
An extractive `NLP` approach for generating release notes from comments and
docstrings added between two git tags.
`releaseup` extracts all the comments and docstrings using `git diff`,
preprocesses the outputs, and finally generates release notes using `sklearn`'s
`TfidfVectorizer` and `spacy`! The generated release notes are not at all
abstractive, which is something `releaseup` aims to achieve in the future.
As of now, `releaseup` is a holiday project (built in mere 2 days), but I do
intend to maintain it in the future. `releaseup` does work, but only if your
comments are well written.
Read more about `releaseup` through its
[documentation](https://releaseup.readthedocs.io).
## Structure
- All the extraction and preprocessing work is carried out using the `extract`
module.
- All the extractive `NLP` work is done inside the `nlp_backend` module.
- `releaseup` also prvides a high level API present inn the `high_level` module.
See [examples](#Examples) for more information.
## Installation
Use `pip` magic
`releaseup` uses modern `Python` packaging and can be installed using `pip` -
```
python -m pip install releaseup
```
For developer install, see our
[Contributing Guidelines](https://github.com/Saransh-cpp/releaseup/blob/main/releaseup).
## Examples
### High level API
```py
import releaseup
tag = ["v0.8.0", "v0.9.0"] # can also be commits
path = "././mypackage/" # to ignore changes made to other folders (./github/, docs/, etc) and files
comments_filename = "COMMENTS.txt"
# extract added comments and docstrings
comments = releaseup.extract_release_comments(tags, path, comments_filename)
release_filename = "RELEASE_NOTES.txt"
# generate release notes
notes = releaseup.generate_release_notes(
comments,
release_filename,
model_name="en_core_web_trf", # any spacy model
threshold=0.3, # percentage of comments to be selected
)
```
### Low level API
```py
from releaseup.extract import (
extract_additions,
get_comments_and_docstrings,
get_diff,
preprocess_additions,
)
from releaseup.nlp_backend import get_release_notes, get_tfid_scores
tag = ["v0.8.0", "v0.9.0"] # can also be commits
path = "././mypackage/" # to ignore changes made to other folders (./github/, docs/, etc) and files
comments_filename = "COMMENTS.txt"
# extract added comments and docstrings
get_diff(tags, path, comments_filename)
extracted_additions = extract_additions(comments_filename)
preprocessed_additions = preprocess_additions(extracted_additions)
comments = get_comments_and_docstrings(preprocessed_additions)
release_filename = "RELEASE_NOTES.txt"
word_score = get_tfid_scores(comments)
release_notes = get_release_notes(
comments,
word_score,
release_filename,
model_name="en_core_web_trf", # any spacy model
threshold=0.3, # percentage of comments to be selected
)
```
## Testing
**TODO: ADD TESTS**
## Activating pre-commit
`releaseup` uses a set of `pre-commit` hooks and the `pre-commit` bot to format,
type-check, and prettify the codebase. The hooks can be installed locally
using -
```
pre-commit install
```
This would run the checks every time a commit is created locally. The checks
will only run on the files modified by that commit, but the checks can be
triggered for all the files using -
```
pre-commit run --all-files
```
If you would like to skip the failing checks and push the code for further
discussion, use the `--no-verify` option with `git commit`.
## Documenting releaseup
`releaseup`'s documentation is mainly written in the form of
[docstrings](https://peps.python.org/pep-0257/) and
[Markdown](https://en.wikipedia.org/wiki/Markdown). The docstrings include the
description, arguments, examples, return values, and attributes of a class or a
function, and the `.md` files enable us to render this documentation on
`releaseup`'s documentation website.
`releaseup` primarily uses [MkDocs](https://www.mkdocs.org/) and
[mkdocstrings](https://mkdocstrings.github.io/) for rendering documentation on
its website. The configuration file (`mkdocs.yml`) for `MkDocs` can be found
[here](https://github.com/Saransh-cpp/releaseup/blob/main/mkdocs.yml). The
documentation is deployed on
[here](https://releaseup.readthedocs.io/en/latest/).
Ideally, with the addition of every new feature to `releaseup`, documentation
should be added using comments, docstrings, and `.md` files.
### Building documentation locally
The documentation is located in the `docs` folder of the main repository. This
documentation can be generated using the `docs` dependencies of `releaseup` in
the following way -
```
mkdocs serve
```
The commands executed above will clean any existing documentation build, create
a new build (in `./site/`), and serve it on your `localhost`. To just build the
documentation, use -
```
mkdocs build
```
## Nox
The fastest way to start with development is to use nox. If you don't have nox,
you can use `pipx run nox` to run it without installing, or `pipx install nox`.
If you don't have pipx (pip for applications), then you can install with with
`pip install pipx` (the only case were installing an application with regular
pip is reasonable). If you use macOS, then pipx and nox are both in brew, use
`brew install pipx nox`.
To use, run `nox`. This will lint and test using every installed version of
Python on your system, skipping ones that are not installed. You can also run
specific jobs:
```console
$ nox -s lint # Lint only
$ nox -s tests-3.9 # Python 3.9 tests only
$ nox -s docs -- serve # Build and serve the docs
$ nox -s build # Make an SDist and wheel
```
The default sessions (`lint` and `tests`) can be executed using -
```
nox
```
## Continuous Integration
`releaseup` uses `GitHub Actions` as a `CI` provider to run tests, build docs,
release on `PyPI`, test package, etc. All the configuration for `GitHub Actions`
is written in `YAML`, present in `.github/` directory. The CI runs every time a
pull request is made or a push is made to the `main` branch.
## Continuous Deployment
`releaseup` uses `Read The Docs` as a `CD` provider to deploy documentation. All
the configuration for `Read The Docs` is written in `YAML`, present in the
`.readthedocs.yml` file. The CD runs every time a push is made to the `main`
branch.
## Credits
Logo image credits: Taufik Ramadhan (taken from canva)