From def61534e11b68095bb0d6e23308096d20ea6611 Mon Sep 17 00:00:00 2001 From: Michael Date: Wed, 2 Sep 2026 20:54:38 +0200 Subject: [PATCH 1/4] =?UTF-8?q?=F0=9F=9A=80=20Prepare=20v2.0.0=20release?= =?UTF-8?q?=20(README,=20docs,=20version=20bump)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Presents v2 as the standard, released version instead of a beta: * README: plain `pip install bibtexparser` (no more `--pre`), with explicit `bibtexparser~=1.0` instructions for those still on v1. Keeps the "much changed since v1" note (now pointing at the migration guide) and the list of v2 advantages. * docs/install: PyPI section first, `--pre` removed, v1 pinning documented, python floor corrected to 3.10 (matches pyproject). * docs/migrate: v2 status is now "stable and recommended". * docs/customize: drop the pre-release caveat on default stacks. * CONTRIBUTING: v2 is the recommended version, v1 in maintenance mode. * Version 2.0.0b9 -> 2.0.0, classifier Beta -> Production/Stable. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01Rmt7yTJ9py96WnHoTStY26 --- CONTRIBUTING.md | 4 ++-- README.md | 12 +++++++----- bibtexparser/__init__.py | 2 +- docs/source/customize.rst | 2 +- docs/source/install.rst | 30 ++++++++++++++++++------------ docs/source/migrate.rst | 6 +++--- pyproject.toml | 2 +- 7 files changed, 33 insertions(+), 25 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5a241303..d95e2a92 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,8 +18,8 @@ We are always looking for people to improve the library. Contributions include, ### Version 1 vs version 2 Also note that there are currently two independent "default" branches: -First, `main`, where we maintain the `v2` of bibtexparser, which is a complete re-write and currently still in beta and not feature complete. -Second, `v1` where we maintain the stable `v1` version of bibtexparser. Note that on `v1` we accept only small, non-breaking changes and are planning to stop support as soon as `v2` reaches reasonable stability. +First, `main`, where we maintain the `v2` of bibtexparser, which is a complete re-write and the current, recommended version. +Second, `v1` where we maintain the legacy `v1` version of bibtexparser. Note that `v1` is in maintenance mode: we accept only small, non-breaking changes there. The two branches are never going to be merged anymore, thus if you want to change something for both versions, you will have to open two PRs. Issues are labelled `v1` and `v2`, correspondingly. diff --git a/README.md b/README.md index 02eacb03..2b16c8d2 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,10 @@ Welcome to python-bibtexparser, a parser for `.bib` files with a long history and wide adoption. -Bibtexparser is available in two versions: V1 and V2. For new projects, we recommend using v2 which, in the long run, will provide an overall more robust and faster experience. **For now, however, note that v2 is still in beta stage, and does not contain all features of v1**. Install v2 using pip: +Bibtexparser is available in two versions: V1 and V2. **V2 is the current, recommended version** and the default you get from PyPI. It provides an overall more robust and faster experience than v1, and is where all development and maintenance effort goes. Install it using pip: ```bash -pip install bibtexparser --pre +pip install bibtexparser ``` Or you can install the latest development version directly from the main branch: @@ -13,14 +13,16 @@ Or you can install the latest development version directly from the main branch: pip install --no-cache-dir --force-reinstall git+https://github.com/sciunto-org/python-bibtexparser@main ``` -If instead, you want to use v1, install it using: +If instead you still need v1, e.g. for a legacy project which you don't want to migrate right now, pin it explicitly: ```bash pip install bibtexparser~=1.0 ``` -Note that all development and maintenance effort is focussed on v2. -Small PRs for v1 are still accepted, but only as long as they are backwards compatible and don't introduce much additional technical debt. +Note that v2 is a rewrite: a lot has changed since v1, including the primary entrypoints, the data structures and the way parsing and writing are customized. +Existing v1 code will not run unchanged on v2 - have a look at our [migration guide](https://bibtexparser.readthedocs.io/en/main/migrate.html) when upgrading. + +V1 is in maintenance mode: small PRs are still accepted, but only as long as they are backwards compatible and don't introduce much additional technical debt. Development of version one happens on the dedicated [v1 branch](https://github.com/sciunto-org/python-bibtexparser/tree/v1). The remainder of this README is specific to v2. diff --git a/bibtexparser/__init__.py b/bibtexparser/__init__.py index 3b7e188f..ec8962d4 100644 --- a/bibtexparser/__init__.py +++ b/bibtexparser/__init__.py @@ -8,4 +8,4 @@ from bibtexparser.library import Library from bibtexparser.writer import BibtexFormat -__version__ = "2.0.0b9" +__version__ = "2.0.0" diff --git a/docs/source/customize.rst b/docs/source/customize.rst index 9b8a2ae4..91c7c210 100644 --- a/docs/source/customize.rst +++ b/docs/source/customize.rst @@ -62,7 +62,7 @@ by selecting the corresponding argument when calling :code:`bibtexparser.parse` * :code:`parse_stack`: Overwrite the default parse stack (similarly :code:`write_stack` for write stack). .. warning:: - The default parse and write stacks may change on **minor** version updates and between pre-releases. + The default parse and write stacks may change on **minor** version updates. To reduce the risk of unnoticed changes in parsing stack, critical applications may want to hard-code the full parse stack in their code using :code:`parse_stack` and :code:`write_stack` arguments. diff --git a/docs/source/install.rst b/docs/source/install.rst index ec23ec38..8aba784e 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -6,33 +6,39 @@ Requirements ------------ -Bibtexparser's only requirement is a python interpreter which is not yet EOL (currently >= 3.9). +Bibtexparser's only requirement is a python interpreter which is not yet EOL (currently >= 3.10). As of version 2.0.0, bibtexparser is a pure-python project (no direct bindings to C libraries). As such, it should be rather easy to install on any platform. -Installation of current development version -------------------------------------------- +Installation from PyPI +-------------------------- -To install the latest version on the main branch (without manually cloning it), run: + +To install the latest release (v2) using pip: .. code-block:: sh - pip install --no-cache-dir --force-reinstall git+https://github.com/sciunto-org/python-bibtexparser@main + pip install bibtexparser +If you still need v1, e.g. for a legacy project which you don't want to migrate right now, +pin the major version explicitly: -Installation from PyPI --------------------------- +.. code-block:: sh + pip install bibtexparser~=1.0 -To install the latest release candidate (currently required to use v2) using pip: +Note that v1 is in maintenance mode, has a different API and is not directly compatible with v2. +See the :doc:`migration guide ` if you are upgrading an existing v1 project. -.. code-block:: sh +Installation of current development version +------------------------------------------- - pip install --pre bibtexparser +To install the latest version on the main branch (without manually cloning it), run: + +.. code-block:: sh -without the ``--pre`` option, you will get the latest v1 version. -It has a different API and is not directly compatible with v2. + pip install --no-cache-dir --force-reinstall git+https://github.com/sciunto-org/python-bibtexparser@main Installation from source diff --git a/docs/source/migrate.rst b/docs/source/migrate.rst index bdd65f6f..9fc151bc 100644 --- a/docs/source/migrate.rst +++ b/docs/source/migrate.rst @@ -8,9 +8,9 @@ and have a quick look at the tutorial to get a feeling for the new API. Status of v2 ------------ -The v2 branch is well tested and reasonably stable, but it is not yet widely adopted - as an early adopter, -you may encounter some bugs. If you do, please report them on the issue tracker. -Also, note that some interfaces may change slightly before we release v2.0.0 as stable. +V2 is released as stable and is the version we recommend for all projects. +It is well tested and receives all development and maintenance effort, while v1 is in maintenance mode. +If you encounter a bug, please report it on the issue tracker. Some customizations from v1 are not implemented in v2, as we doubt they are widely used. If you need one of these features, please let us know on the issue tracker. diff --git a/pyproject.toml b/pyproject.toml index ad2db6b5..b35fdd47 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ requires = ["setuptools>=77"] [project] authors = [{name = "Michael Weiss and other contributors", email = "code@mweiss.ch"}] classifiers = [ - "Development Status :: 4 - Beta", + "Development Status :: 5 - Production/Stable", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", From 4f48504ffe2ae505f3f4347497ff95c801fc246e Mon Sep 17 00:00:00 2001 From: Michael Weiss Date: Thu, 3 Sep 2026 20:47:47 +0200 Subject: [PATCH 2/4] Update README with v2 migration and maintainer info Clarify v2 migration details and update maintainer credits. --- README.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 2b16c8d2..9275997a 100644 --- a/README.md +++ b/README.md @@ -20,13 +20,11 @@ pip install bibtexparser~=1.0 ``` Note that v2 is a rewrite: a lot has changed since v1, including the primary entrypoints, the data structures and the way parsing and writing are customized. -Existing v1 code will not run unchanged on v2 - have a look at our [migration guide](https://bibtexparser.readthedocs.io/en/main/migrate.html) when upgrading. +Existing v1 code will not run unchanged on v2 - have a look at our [migration guide](https://bibtexparser.readthedocs.io/en/main/migrate.html) when upgrading. While v2 has been thoroughly tested and has been in pre-release for a long time, please don't hesitate to report any issues you may encounter. V1 is in maintenance mode: small PRs are still accepted, but only as long as they are backwards compatible and don't introduce much additional technical debt. Development of version one happens on the dedicated [v1 branch](https://github.com/sciunto-org/python-bibtexparser/tree/v1). -The remainder of this README is specific to v2. - ## Documentation Go check out our documentation on [https://bibtexparser.readthedocs.io/en/main/](https://bibtexparser.readthedocs.io/en/main/). @@ -71,9 +69,9 @@ new_bibtex_string = bibtexparser.write_string(bib_database, These examples really only show the bare minimum. Consult the documentation for a list of available middleware, parsing options and write-formatting options. -## V2 Architecture and Terminology +## Architecture and Terminology -![bibtexparserv2](https://user-images.githubusercontent.com/4815944/193734283-f19f94e8-7986-4acf-b1a3-1d215e297224.png) +![bibtexparser](https://user-images.githubusercontent.com/4815944/193734283-f19f94e8-7986-4acf-b1a3-1d215e297224.png) The architecture consists of the following components: @@ -92,7 +90,7 @@ Writes the content of a bibtex library to a ``.bib`` file. Optional formatting p ## About -Since 2022, `bibtexparser` is primarily written and maintained by Michael Weiss ([@MiWeiss](https://github.com/MiWeiss/)). In 2024, Tom de Geus ([@tdegeus](https://github.com/tdegeus)) joined as co-maintainer. +Since 2022, `bibtexparser` is primarily written and maintained by Michael Weiss ([@MiWeiss](https://github.com/MiWeiss/)), supported by various awesome contributors. Credits and thanks to the many contributors who helped creating this library, including François Boulogne ([@sciunto](https://github.com/sciunto/), creator of the first version) and Olivier Mangin ([@omangin](https://github.com/omangin/), long-term contributor). From f0cc14ade1c950e55a754f5679f96092fe231728 Mon Sep 17 00:00:00 2001 From: Michael Weiss Date: Thu, 3 Sep 2026 20:49:58 +0200 Subject: [PATCH 3/4] Fix formatting in README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9275997a..2a2cbf9a 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,7 @@ Writes the content of a bibtex library to a ``.bib`` file. Optional formatting p ## About -Since 2022, `bibtexparser` is primarily written and maintained by Michael Weiss ([@MiWeiss](https://github.com/MiWeiss/)), supported by various awesome contributors. +Since 2022, `bibtexparser` is primarily written and maintained by Michael Weiss ([@MiWeiss](https://github.com/MiWeiss/)), supported by various awesome contributors. Credits and thanks to the many contributors who helped creating this library, including François Boulogne ([@sciunto](https://github.com/sciunto/), creator of the first version) and Olivier Mangin ([@omangin](https://github.com/omangin/), long-term contributor). From a564b5f1119c329b67b539c702224366e3277af8 Mon Sep 17 00:00:00 2001 From: Michael Weiss Date: Thu, 3 Sep 2026 22:12:30 +0200 Subject: [PATCH 4/4] Update section title for advantages of v2 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2a2cbf9a..8faa0a1d 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Development of version one happens on the dedicated [v1 branch](https://github.c ## Documentation Go check out our documentation on [https://bibtexparser.readthedocs.io/en/main/](https://bibtexparser.readthedocs.io/en/main/). -## Advantages of V2 +## Advantages of `v2` compared to `v1` - :rocket: Order of magnitudes faster - :wrench: Easily customizable parsing **and** writing