Browse Source

Document how to develop on and contribute to borgmatic.

tags/1.2.0
Dan Helfman 2 years ago
parent
commit
219e287c6c
2 changed files with 56 additions and 15 deletions
  1. +1
    -0
      NEWS
  2. +55
    -15
      README.md

+ 1
- 0
NEWS View File

@@ -11,6 +11,7 @@
archive.
* Update tox.ini to only assume Python 3.x instead of Python 3.4 specifically.
* Add ~/.config/borgmatic/config.yaml to default configuration path probing.
* Document how to develop on and contribute to borgmatic.

1.1.15
* Support for Borg BORG_PASSCOMMAND environment variable to read a password from an external file.


+ 55
- 15
README.md View File

@@ -304,15 +304,66 @@ Feel free to modify the timer file based on how frequently you'd like
borgmatic to run.


## Running tests
## Support and contributing

First, clone a copy of [borgmatic source code](https://projects.torsion.org/witten/borgmatic):
### Issues

You've got issues? Or an idea for a feature enhancement? We've got an [issue
tracker](https://projects.torsion.org/witten/borgmatic/issues). In order to
create a new issue or comment on an issue, you'll need to [login
first](https://projects.torsion.org/user/login). Note that you can login with
an existing GitHub account if you prefer.

Other questions or comments? Contact <mailto:witten@torsion.org>.


### Contributing

If you'd like to contribute to borgmatic development, please feel free to
submit a [Pull Request](https://projects.torsion.org/witten/borgmatic/pulls)
or open an [issue](https://projects.torsion.org/witten/borgmatic/issues) first
to discuss your idea. We also accept Pull Requests on GitHub, if that's more
your thing. In general, contributions are very welcome. We don't bite!


### Development

To get set up to hack on borgmatic, first clone master via HTTPS or SSH:

```
git clone https://projects.torsion.org/witten/borgmatic.git
```

Or:

```bash
git clone https://projects.torsion.org/witten/borgmatic
git clone ssh://git@projects.torsion.org:3022/witten/borgmatic.git
```

Then, install tox, which is used for setting up testing environments:
Then, install borgmatic
"[editable](https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs)"
so that you can easily run borgmatic commands while you're hacking on them to
make sure your changes work.

```bash
cd borgmatic/
pip3 install --editable --user .
```

Note that this will typically install the borgmatic commands into
`~/.local/bin`, which may or may not be on your PATH. There are other ways to
install borgmatic editable as well, for instance into the system Python
install (so without `--user`, as root), or even into a
[virtualenv](https://virtualenv.pypa.io/en/stable/). How or where you install
borgmatic is up to you, but generally an editable install makes development
and testing easier.


### Running tests

Assuming you've cloned the borgmatic source code as described above, and
you're in the `borgmatic/` working copy, install tox, which is used for
setting up testing environments:

```bash
sudo pip3 install tox
@@ -360,14 +411,3 @@ YAML library. If so, not to worry. borgmatic should install and function
correctly even without the C YAML library. And borgmatic won't be any faster
with the C library present, so you don't need to go out of your way to install
it.


## Issues and feedback

Got an issue or an idea for a feature enhancement? Check out the [borgmatic
issue tracker](https://projects.torsion.org/witten/borgmatic/issues). In order
to create a new issue or comment on an issue, you'll need to [login
first](https://projects.torsion.org/user/login). Note that you can login with
an existing GitHub account if you prefer.

Other questions or comments? Contact <mailto:witten@torsion.org>.

Loading…
Cancel
Save