|
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