1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
Contributing code
=================
How to contribute
-----------------
The preferred way to contribute to librosa is to fork the
[main repository](http://github.com/librosa/librosa/) on
GitHub:
1. Fork the [project repository](http://github.com/librosa/librosa):
click on the 'Fork' button near the top of the page. This creates
a copy of the code under your account on the GitHub server.
2. Clone this copy to your local disk:
$ git clone --recursive git@github.com:YourLogin/librosa.git
$ cd librosa
$ git pull --recurse-submodules
These commands will clone the main librosa repository, as well as the submodule
that contains testing data. This should work automatically, but you may also
want to read [Working with Submodules](https://github.blog/2016-02-01-working-with-submodules/)
for a better understanding of how this works.
3. Set the upstream remote to the Librosa's repo:
$ git remote add upstream git@github.com:librosa/librosa.git
4. Create a new conda environment in order to install dependencies:
$ conda create -n librosa-dev python=3.9
$ conda env update -n librosa-dev --file .github/environment-ci.yml
$ conda activate librosa-dev
$ python -m pip install -e '.[tests]'
5. Create a branch to hold your changes:
$ git switch -c <NAME-NEW-BRANCH>
and start making changes. Never work in the ``main`` branch!
6. Work on this copy on your computer using Git to do the version
control. You can check your modified files using:
$ git status
7. When you're done editing, do:
$ git add <PATH-TO-MODIFIED-FILES>
$ git commit -m "<COMMIT-MESSAGE>"
to record your changes in Git, then push them to GitHub with:
$ git push --set-upstream origin <NAME-NEW-BRANCH>
8. Go to the web page of your fork of the librosa repo,
and click 'Pull request' to review your changes and add a description
of what you did.
Finally, click 'Create pull request' to send your changes to the
maintainers for review. This will send an email to the committers.
(If any of the above seems like magic to you, then look up the
[Git documentation](http://git-scm.com/documentation) on the web.)
It is recommended to check that your contribution complies with the
following rules before submitting a pull request:
- All functions should have informative [docstrings](https://numpydoc.readthedocs.io/en/latest/format.html) with sample usage presented.
You can also check for common programming errors with the following
tools:
- Code with good test coverage, check with:
$ pytest
- No pyflakes warnings, check with:
$ python -m pip install flake8
$ flake8 librosa
Some tests in tests/test_display.py use baseline images for output comparison.
If existing images need to be updated or new ones should be added:
1. Ensure that the environment is properly setup for testing (pytest with addons)
2. Run:
$ pytest --mpl-generate-path=tmp tests/test_display.py [-k ANY_TESTS_THAT_CHANGED]
3. Inspect the new baseline images under tmp/
4. If (3) looks good, copy into `tests/baseline_images/test_display/` and add to the PR.
Additionally, some functions require network access to test properly.
If you are adding tests that require network access, please mark them with `@pytest.mark.network`.
Finally, once your pull request has been created and reviewed, please update the file `docs/changelog.rst`
to briefly summarize your contribution in the section for the next release.
If you are a first-time contributor, please add yourself to `AUTHORS.md` as well.
Filing bugs
-----------
We use Github issues to track all bugs and feature requests; feel free to
open an issue if you have found a bug or wish to see a feature implemented.
It is recommended to check that your issue complies with the
following rules before submitting:
- Verify that your issue is not being currently addressed by other
[issues](https://github.com/librosa/librosa/issues?q=)
or [pull requests](https://github.com/librosa/librosa/pulls?q=).
- Please ensure all code snippets and error messages are formatted in
appropriate code blocks.
See [Creating and highlighting code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks).
- Please include your operating system type and version number, as well
as your Python, librosa, numpy, and scipy versions. This information
can be found by running the following code snippet:
```python
import platform; print(platform.platform())
import sys; print("Python", sys.version)
import numpy; print("NumPy", numpy.__version__)
import scipy; print("SciPy", scipy.__version__)
import librosa; print("librosa", librosa.__version__)
```
Documentation
-------------
You can edit the documentation using any text editor and then generate
the HTML output by typing ``make html`` from the docs/ directory.
The resulting HTML files will be placed in _build/html/ and are viewable
in a web browser. See the README file in the doc/ directory for more information.
For building the documentation, you will need some additional dependencies.
These can be installed by executing the following command:
$ python -m pip install -e '.[docs]'
Note
----
This document was gleefully borrowed from [scikit-learn](http://scikit-learn.org/).
|
