|
1 | | -.. highlight:: shell |
2 | | - |
| 1 | +============ |
3 | 2 | Contributing |
4 | 3 | ============ |
5 | 4 |
|
6 | | -Contributions are welcome, and they are greatly appreciated! Every little bit |
7 | | -helps, and credit will always be given. |
8 | | - |
9 | | -You can contribute in many ways: |
10 | | - |
11 | | -Types of Contributions |
12 | | ----------------------- |
13 | | - |
14 | | -Report Bugs |
15 | | -~~~~~~~~~~~ |
16 | | - |
17 | | -Report bugs at https://github.com/sdv-dev/Copulas/issues. |
18 | | - |
19 | | -If you are reporting a bug, please include: |
20 | | - |
21 | | -* Your operating system name and version. |
22 | | -* Any details about your local setup that might be helpful in troubleshooting. |
23 | | -* Detailed steps to reproduce the bug. |
24 | | - |
25 | | -Fix Bugs |
26 | | -~~~~~~~~ |
27 | | - |
28 | | -Look through the GitHub issues for bugs. Anything tagged with "bug" and "help |
29 | | -wanted" is open to whoever wants to implement it. |
30 | | - |
31 | | -Implement Features |
32 | | -~~~~~~~~~~~~~~~~~~ |
33 | | - |
34 | | -Look through the GitHub issues for features. Anything tagged with "enhancement" |
35 | | -and "help wanted" is open to whoever wants to implement it. |
36 | | - |
37 | | -Write Documentation |
38 | | -~~~~~~~~~~~~~~~~~~~ |
39 | | - |
40 | | -Copulas could always use more documentation, whether as part of the |
41 | | -official Copulas docs, in docstrings, or even on the web in blog posts, |
42 | | -articles, and such. |
43 | | - |
44 | | -Submit Feedback |
45 | | -~~~~~~~~~~~~~~~ |
46 | | - |
47 | | -The best way to send feedback is to file an issue at https://github.com/sdv-dev/Copulas/issues. |
48 | | - |
49 | | -If you are proposing a feature: |
50 | | - |
51 | | -* Explain in detail how it would work. |
52 | | -* Keep the scope as narrow as possible, to make it easier to implement. |
53 | | -* Remember that this is a volunteer-driven project, and that contributions |
54 | | - are welcome :) |
55 | | - |
56 | | -Get Started! |
57 | | ------------- |
58 | | - |
59 | | -Ready to contribute? Here's how to set up `Copulas` for local development. |
60 | | - |
61 | | -1. Fork the `Copulas` repo on GitHub. |
62 | | -2. Clone your fork locally:: |
63 | | - |
64 | | - $ git clone [email protected]:your_name_here/Copulas.git |
65 | | - |
66 | | -3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, |
67 | | - this is how you set up your fork for local development:: |
68 | | - |
69 | | - $ mkvirtualenv Copulas |
70 | | - $ cd Copulas/ |
71 | | - $ make install-develop |
72 | | - |
73 | | -4. Create a branch for local development:: |
74 | | - |
75 | | - $ git checkout -b name-of-your-bugfix-or-feature |
76 | | - |
77 | | - Now you can make your changes locally. |
78 | | - |
79 | | -5. While hacking your changes, make sure to cover all your developments with the required |
80 | | - unit tests, and that none of the old tests fail as a consequence of your changes. |
81 | | - For this, make sure to run the tests suite and check the code coverage:: |
82 | | - |
83 | | - $ make test # Run the tests |
84 | | - $ make coverage # Get the coverage report |
85 | | - |
86 | | -6. When you're done making changes, check that your changes pass flake8 and the |
87 | | - tests, including testing other Python versions with tox:: |
88 | | - |
89 | | - $ make test-all |
90 | | - |
91 | | -7. Make also sure to include the necessary documentation in the code as docstrings following |
92 | | - the [google](https://google.github.io/styleguide/pyguide.html?showone=Comments#38-comments-and-docstrings) |
93 | | - docstring style. If you want to view how your documentation will look like when it is |
94 | | - published, you can generate and view the docs with this commands:: |
95 | | - |
96 | | - $ make docs |
97 | | - $ make view-docs |
98 | | - |
99 | | -8. Commit your changes and push your branch to GitHub:: |
100 | | - |
101 | | - $ git add . |
102 | | - $ git commit -m "Your detailed description of your changes." |
103 | | - $ git push origin name-of-your-bugfix-or-feature |
104 | | - |
105 | | -9. Submit a pull request through the GitHub website. |
106 | | - |
107 | | -Pull Request Guidelines |
108 | | ------------------------ |
109 | | - |
110 | | -Before you submit a pull request, check that it meets these guidelines: |
111 | | - |
112 | | -1. It resolves an open GitHub Issue and contains its reference in the title or |
113 | | - the comment. If there is no associated issue, feel free to create one. |
114 | | -2. Whenever possible, it resolves only **one** issue. If your PR resolves more than |
115 | | - one issue, try to split it in more than one pull request. |
116 | | -3. The pull request should include unit tests that cover all the changed code |
117 | | -4. If the pull request adds functionality, the docs should be updated. Put |
118 | | - your new functionality into a function with a docstring, and add the |
119 | | - feature to the list in README.rst. |
120 | | -5. The pull request should work for all the supported Python versions. Check |
121 | | - https://github.com/sdv-dev/Copulas/actions and make sure that all the checks pass. |
122 | | - |
123 | | -Unit Testing Guidelines |
124 | | ------------------------ |
125 | | - |
126 | | -All the Unit Tests should comply with the following requirements: |
127 | | - |
128 | | -1. Unit Tests should be based only in unittest and pytest modules. |
129 | | - |
130 | | -2. The tests that cover a module called ``copulas/path/to/a_module.py`` should be |
131 | | - implemented in a separated module called ``tests/copulas/path/to/test_a_module.py``. |
132 | | - Note that the module name has the ``test_`` prefix and is located in a path similar |
133 | | - to the one of the tested module, just inside te ``tests`` folder. |
134 | | - |
135 | | -3. Each method of the tested module should have at least one associated test method, and |
136 | | - each test method should cover only **one** use case or scenario. |
137 | | - |
138 | | -4. Test case methods should start with the ``test_`` prefix and have descriptive names |
139 | | - that indicate which scenario they cover. |
140 | | - Names such as ``test_some_methed_input_none``, ``test_some_method_value_error`` or |
141 | | - ``test_some_method_timeout`` are right, but names like ``test_some_method_1``, |
142 | | - ``some_method`` or ``test_error`` are not. |
143 | | - |
144 | | -5. Each test should validate only what the code of the method being tested does, and not |
145 | | - cover the behavior of any third party package or tool being used, which is assumed to |
146 | | - work properly as far as it is being passed the right values. |
147 | | - |
148 | | -6. Any third party tool that may have any kind of random behavior, such as some Machine |
149 | | - Learning models, databases or Web APIs, will be mocked using the ``mock`` library, and |
150 | | - the only thing that will be tested is that our code passes the right values to them. |
151 | | - |
152 | | -7. Unit tests should not use anything from outside the test and the code being tested. This |
153 | | - includes not reading or writting to any filesystem or database, which will be properly |
154 | | - mocked. |
155 | | - |
156 | | -Tips |
157 | | ----- |
158 | | - |
159 | | -To run a subset of tests:: |
160 | | - |
161 | | - $ pytest tests.test_copulas |
162 | | - |
163 | | -Release Workflow |
164 | | ----------------- |
165 | | - |
166 | | -The process of releasing a new version involves several steps combining both ``git`` and |
167 | | -``bumpversion`` which, briefly: |
168 | | - |
169 | | -1. Merge what is in ``main`` branch into ``stable`` branch. |
170 | | -2. Update the version in ``setup.cfg``, ``copulas/__init__.py`` and ``HISTORY.md`` files. |
171 | | -3. Create a new TAG pointing at the correspoding commit in ``stable`` branch. |
172 | | -4. Merge the new commit from ``stable`` into ``main``. |
173 | | -5. Update the version in ``setup.cfg`` and ``copulas/__init__.py`` to open the next |
174 | | - development interation. |
175 | | - |
176 | | -**Note:** Before starting the process, make sure that ``HISTORY.md`` has a section titled |
177 | | -**Unreleased** with the list of changes that will be included in the new version, and that |
178 | | -these changes are committed and available in ``main`` branch. |
179 | | -Normally this is just a list of the Pull Requests that have been merged since the latest version. |
180 | | - |
181 | | -Once this is done, run of the following commands: |
182 | | - |
183 | | -1. If you are releasing a patch version:: |
184 | | - |
185 | | - make release |
| 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. |
186 | 8 |
|
187 | | -2. If you are releasing a minor version:: |
| 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. |
188 | 14 |
|
189 | | - make release-minor |
| 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. |
190 | 21 |
|
191 | | -3. If you are releasing a major version:: |
192 | 22 |
|
193 | | - make release-major |
| 23 | +.. _Business Source License: https://github.com/sdv-dev/Copulas/blob/main/LICENSE |
| 24 | +.. _file an issue: https://github.com/sdv-dev/Copulas/issues |
0 commit comments