|
1 | | -.. highlight:: shell |
2 | | - |
3 | 1 | ============ |
4 | 2 | Contributing |
5 | 3 | ============ |
6 | 4 |
|
7 | | -Contributions are welcome, and they are greatly appreciated! Every little bit |
8 | | -helps, and credit will always be given. |
9 | | - |
10 | | -You can contribute in many ways: |
11 | | - |
12 | | -Types of Contributions |
13 | | ----------------------- |
14 | | - |
15 | | -Report Bugs |
16 | | -~~~~~~~~~~~ |
17 | | - |
18 | | -Report bugs at the `GitHub Issues page`_. |
19 | | - |
20 | | -If you are reporting a bug, please include: |
21 | | - |
22 | | -* Your operating system name and version. |
23 | | -* Any details about your local setup that might be helpful in troubleshooting. |
24 | | -* Detailed steps to reproduce the bug. |
25 | | - |
26 | | -Fix Bugs |
27 | | -~~~~~~~~ |
28 | | - |
29 | | -Look through the GitHub issues for bugs. Anything tagged with "bug" and "help |
30 | | -wanted" is open to whoever wants to implement it. |
31 | | - |
32 | | -Implement Features |
33 | | -~~~~~~~~~~~~~~~~~~ |
34 | | - |
35 | | -Look through the GitHub issues for features. Anything tagged with "enhancement" |
36 | | -and "help wanted" is open to whoever wants to implement it. |
37 | | - |
38 | | -Write Documentation |
39 | | -~~~~~~~~~~~~~~~~~~~ |
40 | | - |
41 | | -SDV could always use more documentation, whether as part of the |
42 | | -official SDV docs, in docstrings, or even on the web in blog posts, |
43 | | -articles, and such. |
44 | | - |
45 | | -Submit Feedback |
46 | | -~~~~~~~~~~~~~~~ |
47 | | - |
48 | | -The best way to send feedback is to file an issue at the `GitHub Issues page`_. |
49 | | - |
50 | | -If you are proposing a feature: |
51 | | - |
52 | | -* Explain in detail how it would work. |
53 | | -* Keep the scope as narrow as possible, to make it easier to implement. |
54 | | -* Remember that this is a volunteer-driven project, and that contributions |
55 | | - are welcome :) |
56 | | - |
57 | | -Get Started! |
58 | | ------------- |
59 | | - |
60 | | -Ready to contribute? Here's how to set up `SDV` for local development. |
61 | | - |
62 | | -1. Fork the `SDV` repo on GitHub. |
63 | | -2. Clone your fork locally:: |
64 | | - |
65 | | - $ git clone [email protected]:your_name_here/SDV.git |
66 | | - |
67 | | -3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, |
68 | | - this is how you set up your fork for local development:: |
69 | | - |
70 | | - $ mkvirtualenv SDV |
71 | | - $ cd SDV/ |
72 | | - $ make install-develop |
73 | | - |
74 | | -4. Create a branch for local development:: |
75 | | - |
76 | | - $ git checkout -b name-of-your-bugfix-or-feature |
77 | | - |
78 | | - Try to use the naming scheme of prefixing your branch with ``gh-X`` where X is |
79 | | - the associated issue, such as ``gh-3-fix-foo-bug``. And if you are not |
80 | | - developing on your own fork, further prefix the branch with your GitHub |
81 | | - username, like ``githubusername/gh-3-fix-foo-bug``. |
82 | | - |
83 | | - Now you can make your changes locally. |
84 | | - |
85 | | -5. While hacking your changes, make sure to cover all your developments with the required |
86 | | - unit tests, and that none of the old tests fail as a consequence of your changes. |
87 | | - For this, make sure to run the tests suite and check the code coverage:: |
88 | | - |
89 | | - $ make lint # Check code styling |
90 | | - $ make test # Run the tests |
91 | | - $ make coverage # Get the coverage report |
92 | | - |
93 | | -6. When you're done making changes, check that your changes pass all the styling checks and |
94 | | - tests, including other Python supported versions, using:: |
95 | | - |
96 | | - $ make test-all |
97 | | - |
98 | | -7. Make also sure to include the necessary documentation in the code as docstrings following |
99 | | - the `Google docstrings style`_. |
100 | | - If you want to view how your documentation will look like when it is published, you can |
101 | | - generate and view the docs with this command:: |
102 | | - |
103 | | - $ make view-docs |
104 | | - |
105 | | -8. Commit your changes and push your branch to GitHub:: |
106 | | - |
107 | | - $ git add . |
108 | | - $ git commit -m "Your detailed description of your changes." |
109 | | - $ git push origin name-of-your-bugfix-or-feature |
110 | | - |
111 | | -9. Submit a pull request through the GitHub website. |
112 | | - |
113 | | -Pull Request Guidelines |
114 | | ------------------------ |
115 | | - |
116 | | -Before you submit a pull request, check that it meets these guidelines: |
117 | | - |
118 | | -1. It resolves an open GitHub Issue and contains its reference in the title or |
119 | | - the comment. If there is no associated issue, feel free to create one. |
120 | | -2. Whenever possible, it resolves only **one** issue. If your PR resolves more than |
121 | | - one issue, try to split it in more than one pull request. |
122 | | -3. The pull request should include unit tests that cover all the changed code. |
123 | | -4. If the pull request adds functionality, the docs should be updated. Put |
124 | | - your new functionality into a function with a docstring, and add the |
125 | | - feature to the documentation in an appropriate place. |
126 | | -5. The pull request should work for all the supported Python versions. |
127 | | - |
128 | | -Unit Testing Guidelines |
129 | | ------------------------ |
130 | | - |
131 | | -All the Unit Tests should comply with the following requirements: |
132 | | - |
133 | | -1. Unit Tests should be based only in unittest and pytest modules. |
134 | | - |
135 | | -2. The tests that cover a module called ``sdv/path/to/a_module.py`` |
136 | | - should be implemented in a separated module called |
137 | | - ``tests/sdv/path/to/test_a_module.py``. |
138 | | - Note that the module name has the ``test_`` prefix and is located in a path similar |
139 | | - to the one of the tested module, just inside the ``tests`` folder. |
140 | | - |
141 | | -3. Each method of the tested module should have at least one associated test method, and |
142 | | - each test method should cover only **one** use case or scenario. |
143 | | - |
144 | | -4. Test case methods should start with the ``test_`` prefix and have descriptive names |
145 | | - that indicate which scenario they cover. |
146 | | - Names such as ``test_some_methed_input_none``, ``test_some_method_value_error`` or |
147 | | - ``test_some_method_timeout`` are right, but names like ``test_some_method_1``, |
148 | | - ``some_method`` or ``test_error`` are not. |
149 | | - |
150 | | -5. Each test should validate only what the code of the method being tested does, and not |
151 | | - cover the behavior of any third party package or tool being used, which is assumed to |
152 | | - work properly as far as it is being passed the right values. |
153 | | - |
154 | | -6. Any third party tool that may have any kind of random behavior, such as some Machine |
155 | | - Learning models, databases or Web APIs, will be mocked using the ``mock`` library, and |
156 | | - the only thing that will be tested is that our code passes the right values to them. |
157 | | - |
158 | | -7. Unit tests should not use anything from outside the test and the code being tested. This |
159 | | - includes not reading or writing to any file system or database, which will be properly |
160 | | - mocked. |
161 | | - |
162 | | -Tips |
163 | | ----- |
164 | | - |
165 | | -To run a subset of tests:: |
166 | | - |
167 | | - $ python -m pytest tests.test_sdv |
168 | | - $ python -m pytest -k 'foo' |
169 | | - |
170 | | -Release Workflow |
171 | | ----------------- |
172 | | - |
173 | | -The process of releasing a new version involves several steps combining both ``git`` and |
174 | | -``bumpversion`` which, briefly: |
175 | | - |
176 | | -1. Merge what is in ``main`` branch into ``stable`` branch. |
177 | | -2. Update the version in ``setup.cfg``, ``sdv/__init__.py`` and |
178 | | - ``HISTORY.md`` files. |
179 | | -3. Create a new git tag pointing at the corresponding commit in ``stable`` branch. |
180 | | -4. Merge the new commit from ``stable`` into ``main``. |
181 | | -5. Update the version in ``setup.cfg`` and ``sdv/__init__.py`` |
182 | | - to open the next development iteration. |
183 | | - |
184 | | -.. note:: Before starting the process, make sure that ``HISTORY.md`` has been updated with a new |
185 | | - entry that explains the changes that will be included in the new version. |
186 | | - Normally this is just a list of the Pull Requests that have been merged to main |
187 | | - since the last release. |
188 | | - |
189 | | -Once this is done, run of the following commands: |
190 | | - |
191 | | -1. If you are releasing a patch version:: |
192 | | - |
193 | | - make release |
194 | | - |
195 | | -2. If you are releasing a minor version:: |
196 | | - |
197 | | - make release-minor |
198 | | - |
199 | | -3. If you are releasing a major version:: |
200 | | - |
201 | | - make release-major |
202 | | - |
203 | | -Release Candidates |
204 | | -~~~~~~~~~~~~~~~~~~ |
205 | | - |
206 | | -Sometimes it is necessary or convenient to upload a release candidate to PyPi as a pre-release, |
207 | | -in order to make some of the new features available for testing on other projects before they |
208 | | -are included in an actual full-blown release. |
209 | | - |
210 | | -In order to perform such an action, you can execute:: |
211 | | - |
212 | | - make release-candidate |
213 | | - |
214 | | -This will perform the following actions: |
215 | | - |
216 | | -1. Build and upload the current version to PyPi as a pre-release, with the format ``X.Y.Z.devN`` |
217 | | - |
218 | | -2. Bump the current version to the next release candidate, ``X.Y.Z.dev(N+1)`` |
219 | | - |
220 | | -After this is done, the new pre-release can be installed by including the ``dev`` section in the |
221 | | -dependency specification, either in ``pyproject.toml``:: |
222 | | - |
223 | | - dependencies = [ |
224 | | - ... |
225 | | - 'sdv>=X.Y.Z.dev', |
226 | | - ... |
227 | | - ] |
| 5 | +We love our community’s interest in the SDV ecosystem. The SDV software |
| 6 | +(and its related libraries) is owned and maintained by DataCebo, Inc. |
| 7 | +It is available under the `Business Source License`_ for you to browse. |
228 | 8 |
|
229 | | -or in command line:: |
| 9 | +We support a large set of users with enterprise-specific intricacies and |
| 10 | +reliability needs. This has required us to be deliberate about setting |
| 11 | +the roadmap for SDV libraries. As a result, we are unable to prioritize |
| 12 | +reviewing and accepting external pull requests. As a policy, we will |
| 13 | +not be able to accept external contributions. |
230 | 14 |
|
231 | | - pip install 'sdv>=X.Y.Z.dev' |
| 15 | +**Would you like a bug or feature request to be addressed?** If you haven't |
| 16 | +already, we would greatly appreciate it if you could `file an issue`_ |
| 17 | +instead with the overall description of your problem. We can determine |
| 18 | +whether it’s aligned with our framework. Once discussed, our team |
| 19 | +typically resolves smaller issues within a few release cycles. |
| 20 | +We appreciate your understanding. |
232 | 21 |
|
233 | 22 |
|
234 | | -.. _GitHub issues page: https://github.com/sdv-dev/SDV/issues |
235 | | -.. _Google docstrings style: https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments |
| 23 | +.. _Business Source License: https://github.com/sdv-dev/SDV/blob/main/LICENSE |
| 24 | +.. _file an issue: https://github.com/sdv-dev/SDV/issues |
0 commit comments