CONTRIBUTING.md

   1 Contributing
   2 ============
   3
   4 All kinds of contributions to Dotbot are greatly appreciated. For someone
   5 unfamiliar with the code base, the most efficient way to contribute is usually
   6 to submit a [feature request](#feature-requests) or [bug report](#bug-reports).
   7 If you want to dive into the source code, you can submit a [patch](#patches) as
   8 well, either working on your own ideas or [existing issues][issues].
   9
  10 Feature Requests
  11 ----------------
  12
  13 Do you have an idea for an awesome new feature for Dotbot? Please [submit a
  14 feature request][issue]. It's great to hear about new ideas.
  15
  16 If you are inclined to do so, you're welcome to [fork][fork] Dotbot, work on
  17 implementing the feature yourself, and submit a patch. In this case, it's
  18 *highly recommended* that you first [open an issue][issue] describing your
  19 enhancement to get early feedback on the new feature that you are implementing.
  20 This will help avoid wasted efforts and ensure that your work is incorporated
  21 into the code base.
  22
  23 Bug Reports
  24 -----------
  25
  26 Did something go wrong with Dotbot? Sorry about that! Bug reports are greatly
  27 appreciated!
  28
  29 When you [submit a bug report][issue], please include relevant information such
  30 as Dotbot version, operating system, configuration file, error messages, and
  31 steps to reproduce the bug. The more details you can include, the easier it is
  32 to find and fix the bug.
  33
  34 Patches
  35 -------
  36
  37 Want to hack on Dotbot? Awesome!
  38
  39 If there are [open issues][issues], you're more than welcome to work on those -
  40 this is probably the best way to contribute to Dotbot. If you have your own
  41 ideas, that's great too! In that case, before working on substantial changes to
  42 the code base, it is *highly recommended* that you first [open an issue][issue]
  43 describing what you intend to work on.
  44
  45 **Patches are generally submitted as pull requests.** Patches are also
  46 [accepted over email][email].
  47
  48 Any changes to the code base should follow the style and coding conventions
  49 used in the rest of the project. The version history should be clean, and
  50 commit messages should be descriptive and [properly
  51 formatted][commit-messages].
  52
  53 When preparing a patch, it's recommended that you add unit tests
  54 that demonstrate the bug is fixed (or that the feature works).
  55 You can run the tests on your local machine by installing the `dev` extras.
  56 The steps below do this using a virtual environment:
  57
  58 ```shell
  59 # Create a local virtual environment
  60 $ python -m venv .venv
  61
  62 # Activate the virtual environment
  63 # Cygwin, Linux, and MacOS:
  64 $ . .venv/bin/activate
  65 # Windows Powershell:
  66 $ & .venv\Scripts\Activate.ps1
  67
  68 # Update pip and setuptools
  69 (.venv) $ python -m pip install -U pip setuptools
  70
  71 # Install dotbot and its development dependencies
  72 (.venv) $ python -m pip install -e .[dev]
  73
  74 # Run the unit tests
  75 (.venv) $ tox
  76 ```
  77
  78 If you prefer to run the tests in an isolated container using Docker, you can
  79 do so with the following:
  80
  81 ```
  82 docker run -it --rm -v "${PWD}:/dotbot" -w /dotbot python:3.10-alpine /bin/sh
  83 ```
  84
  85 After spawning the container, follow the same instructions as above (create a
  86 virtualenv, ..., run the tests).
  87
  88 ---
  89
  90 If you have any questions about anything, feel free to [ask][email]!
  91
  92 [issue]: https://github.com/anishathalye/dotbot/issues/new
  93 [issues]: https://github.com/anishathalye/dotbot/issues
  94 [fork]: https://github.com/anishathalye/dotbot/fork
  95 [email]: mailto:me@anishathalye.com
  96 [commit-messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html