diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5a24130..d95e2a9 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 02eacb0..8faa0a1 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,22 +13,22 @@ 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. -Development of version one happens on the dedicated [v1 branch](https://github.com/sciunto-org/python-bibtexparser/tree/v1). +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. 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. -The remainder of this README is specific to v2. +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). ## 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 @@ -69,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: @@ -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/)). 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). diff --git a/bibtexparser/__init__.py b/bibtexparser/__init__.py index 3b7e188..ec8962d 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 7907ad3..8e2e449 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 ec23ec3..8aba784 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 bdd65f6..9fc151b 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 ad2db6b..b35fdd4 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",