Skip to content

Commit fff948d

Browse files
authored
Update CONTRIBUTING.rst file (#2404)
1 parent ad28ad5 commit fff948d

File tree

1 file changed

+16
-227
lines changed

1 file changed

+16
-227
lines changed

CONTRIBUTING.rst

Lines changed: 16 additions & 227 deletions
Original file line numberDiff line numberDiff line change
@@ -1,235 +1,24 @@
1-
.. highlight:: shell
2-
31
============
42
Contributing
53
============
64

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.
2288

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.
23014

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.
23221

23322

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

Comments
 (0)