# Migration notes

Migration and deprecation notes for libvcs are here, see {ref}`history` as well.

```{admonition} Welcome on board! 👋
1. 📌 For safety, **always** pin the package
2. 📖 Check the migration notes _(You are here)_
3. 📣 If you feel something got deprecated and it interrupted you - past, present, or future - voice your opinion on the [tracker].

   We want to make libvcs fun, reliable, and useful for users.

   API changes can be painful.

   If we can do something to draw the sting, we'll do it. We're taking a balanced approach. That's why these notes are here!

   (Please pin the package. 🙏)

   [tracker]: https://github.com/vcs-python/libvcs/discussions
```

## Next release

_Notes on the upcoming release will be added here_

<!-- Maintainers, insert migration notes for the next release here -->

### pytest fixtures: `gitconfig` / `hgconfig` renamed to `vcs_gitconfig` / `vcs_hgconfig` (#528)

- pytest: `gitconfig` renamed to `vcs_gitconfig`
- pytest: `set_gitconfig` renamed to `set_vcs_gitconfig`
- pytest: `hgconfig` renamed to `vcs_hgconfig`
- pytest: `set_hgconfig` renamed to `set_vcs_hgconfig`

The unprefixed names collided with the third-party
[`pytest-gitconfig`](https://pypi.org/project/pytest-gitconfig/) plugin,
which exposes a `gitconfig` fixture returning a `GitConfig` helper rather
than a `pathlib.Path`. When both plugins auto-loaded, downstream tests
crashed with `AttributeError: 'PosixPath' object has no attribute 'set'`.

No deprecation alias is provided -- update parameter names in test
suites, conftests, and any embedded `pytester.makeconftest` text that
references these fixtures.

### pytest fixtures: `git_local_clone` renamed to `example_git_repo` (#468)

- pytest: `git_local_clone` renamed to `example_git_repo`

### Commands: Listing method renamed (#466)

- `libvcs.cmd.git.GitCmd._list()` -> `libvcs.cmd.git.Git.ls()`
- `libvcs.cmd.svn.Svn._list()` -> `libvcs.cmd.svn.Svn.ls()`

## libvcs 0.30.0 (2024-06-18)

### URLs: Variable renamings and moves (#463)

- `RE_PIP_REV` moved from `libvcs.url.git` to `libvcs.url.constants`.
- `RE_PATH` has changed:

  - The pattern for user matching (e.g., `git@`) has been extracted to `RE_USER`.
  - `RE_PATH` and `SCP_REGEX` (now `RE_SCP`) no longer include user regex pattern
  - Existing patterns now use `RE_USER` explicitly.

- `REGEX_SCP` renamed to `RE_SCP` for consistency.

## libvcs 0.20.0 (2022-10-31)

### URLs: Mapping now class attributes (#433)

`URL.rule_map` is now a class attribute rather than a dataclass attribute.

Before Python 3.11 rejected mutable dataclass defaults:

```python
>>> import dataclasses
>>> from libvcs.url.base import RuleMap
>>> @dataclasses.dataclass(repr=False)
... class GitLabURL:
...     rule_map: RuleMap = RuleMap(_rule_map={})
Traceback (most recent call last):
...
ValueError: mutable default <class 'libvcs.url.base.RuleMap'> for field rule_map is not allowed: use default_factory
```

After release:

```python
>>> import dataclasses
>>> from libvcs.url.base import RuleMap
>>> from libvcs.url.git import GitURL, DEFAULT_RULES
>>> @dataclasses.dataclass(repr=False)
... class MyGitURL(GitURL):
...     rule_map = RuleMap(
...         _rule_map={'gitlab_prefix': DEFAULT_RULES}
...     )
```

<!---
# vim: set filetype=markdown:
-->
