Skip to content

Commit 9e67963

Browse files
davidismdavidism
authored
Merge pull request pallets-eco#726 from lbeaufort/723-add-contributing-doc
Add Contributing docs, add donate section to README
2 parents 82720c6 + 93aa9ca commit 9e67963

File tree

3 files changed

+252
-22
lines changed

3 files changed

+252
-22
lines changed

‎.github/ISSUE_TEMPLATE.md

Lines changed: 6 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,10 @@
1-
**This issue tracker is a tool to address bugs and feature requests in
2-
Flask-SQLAlchemy itself. Please use the [#pocoo IRC channel on freenode](http://flask.pocoo.org/community/irc/)
3-
or [Stack Overflow](https://stackoverflow.com/questions/tagged/flask-sqlalchemy?sort=linked) for general questions about using Flask-SQLAlchemy
4-
or issues not related to Flask-SQLAlchemy.**
1+
Read and remove this section before submitting your issue. Also read
2+
CONTRIBUTING.rst for detailed instructions.
53

6-
If you'd like to report a issue in Flask-SQLAlchemy, fill out the template below.
7-
Provide any extra information that may be useful / related to your problem.
8-
Ideally, create a [minimal, complete, and verifiable example (MCVE)](https://stackoverflow.com/help/mcve),
9-
which helps us understand the problem and helps check that it is not caused
10-
by something in your code.
11-
12-
Flask-SQLAlchemy is a thin wrapper that combines [Flask](https://github.com/pallets/flask) and [SQLAlchemy](https://github.com/sqlalchemy/sqlalchemy). Please
13-
make sure your issue is **actually with Flask-SQLAlchemy and not SQLAlchemy** before
14-
submitting. Consider checking the traceback to see if the error is coming from SQLAlchemy,
15-
or checking if your issue has already been reported as a [SQLAlchemy issue on GitHub](https://github.com/sqlalchemy/sqlalchemy/issues).
16-
17-
Also, please be kind - this project is maintained by volunteers. We appreciate
18-
you taking the time to provide the information needed to address your issue.
4+
This issue tracker is a tool to address bugs and feature requests in
5+
Flask-SQLAlchemy itself. Use Discord or Stack Overflow for questions
6+
about using Flask-SQLAlchemy or issues with your own code. Ensure your
7+
issue is with Flask-SQLAlchemy and not SQLAlchemy itself.
198

209
---
2110

@@ -37,7 +26,6 @@ Paste the full traceback if there was an exception.
3726

3827
### Environment
3928

40-
* Operating system:
4129
* Python version:
4230
* Flask-SQLAlchemy version:
4331
* SQLAlchemy version:

‎CONTRIBUTING.rst

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
How to contribute to Flask-SQLAlchemy
2+
=====================================
3+
4+
Thank you for considering contributing to Flask-SQLAlchemy!
5+
6+
7+
Support questions
8+
-----------------
9+
10+
Please, don't use the issue tracker for this. The issue tracker is a
11+
tool to address bugs and feature requests in Flask-SQLAlchemy itself.
12+
Use one of the following resources for questions about using
13+
Flask-SQLAlchemy or issues with your own code:
14+
15+
- The ``#get-help`` channel on our Discord chat:
16+
https://discord.gg/t6rrQZH
17+
- The mailing list [email protected] for long term discussion or larger
18+
issues.
19+
- Ask on `Stack Overflow`_. Search with Google first using:
20+
``site:stackoverflow.com flask sqlalchemy {search term, exception message, etc.}``
21+
22+
.. _Stack Overflow: https://stackoverflow.com/questions/tagged/flask-sqlalchemy?sort=linked
23+
24+
25+
Reporting issues
26+
----------------
27+
28+
Flask-SQLAlchemy is a thin wrapper that combines Flask and SQLAlchemy.
29+
Make sure your issue is actually with Flask-SQLAlchemy and not
30+
SQLAlchemy before submitting it. Check the traceback to see if the error
31+
is coming from SQLAlchemy. Check if your issue has already been reported
32+
to `SQLAlchemy`_.
33+
34+
Include the following information in your post:
35+
36+
- Describe what you expected to happen.
37+
- If possible, include a `minimal reproducible example`_ to help us
38+
identify the issue. This also helps check that the issue is not with
39+
your own code.
40+
- Describe what actually happened. Include the full traceback if there
41+
was an exception.
42+
- List your Python, Flask-SQLAlchemy, and SQLAlchemy versions. If
43+
possible, check if this issue is already fixed in the latest
44+
releases or the latest code in the repository.
45+
46+
.. _SQLAlchemy: https://github.com/sqlalchemy/sqlalchemy/issues
47+
.. _minimal reproducible example: https://stackoverflow.com/help/minimal-reproducible-example
48+
49+
50+
Submitting patches
51+
------------------
52+
53+
If there is not an open issue for what you want to submit, prefer
54+
opening one for discussion before working on a PR. You can work on any
55+
issue that doesn't have an open PR linked to it or a maintainer assigned
56+
to it. These show up in the sidebar. No need to ask if you can work on
57+
an issue that interests you.
58+
59+
Include the following in your patch:
60+
61+
- Use `Black`_ to format your code. This and other checks will run
62+
automatically if you install `pre-commit`_ using the instructions
63+
below.
64+
- Include tests if your patch adds or changes code. Make sure the test
65+
fails without your patch.
66+
- Update any relevant docs pages and docstrings. Docs pages and
67+
docstrings should be wrapped at 72 characters.
68+
- Add an entry in ``CHANGES.rst``. Use the same style as other
69+
entries. Also include ``.. versionchanged::`` inline changelogs in
70+
relevant docstrings.
71+
72+
.. _Black: https://black.readthedocs.io
73+
.. _pre-commit: https://pre-commit.com
74+
75+
76+
First time setup
77+
~~~~~~~~~~~~~~~~
78+
79+
- Download and install the `latest version of git`_.
80+
- Configure git with your `username`_ and `email`_.
81+
82+
.. code-block:: text
83+
84+
$ git config --global user.name 'your name'
85+
$ git config --global user.email 'your email'
86+
87+
- Make sure you have a `GitHub account`_.
88+
- Fork Flask-SQLAlchemy to your GitHub account by clicking the `Fork`_
89+
button.
90+
- `Clone`_ the main repository locally.
91+
92+
.. code-block:: text
93+
94+
$ git clone https://github.com/pallets/flask-sqlalchemy
95+
$ cd flask-sqlalchemy
96+
97+
- Add your fork as a remote to push your work to. Replace
98+
``{username}`` with your username.
99+
100+
.. code-block:: text
101+
102+
git remote add fork https://github.com/{username}/flask-sqlalchemy
103+
104+
- Create a virtualenv.
105+
106+
.. code-block:: text
107+
108+
$ python3 -m venv env
109+
$ . env/bin/activate
110+
111+
On Windows, activating is different.
112+
113+
.. code-block:: text
114+
115+
> env\Scripts\activate
116+
117+
- Install Flask-SQLAlchemy in editable mode with development
118+
dependencies.
119+
120+
.. code-block:: text
121+
122+
$ pip install -e . -r requirements/dev.txt
123+
124+
- Install the pre-commit hooks.
125+
126+
.. code-block:: text
127+
128+
$ pre-commit install
129+
130+
.. _latest version of git: https://git-scm.com/downloads
131+
.. _username: https://help.github.com/en/articles/setting-your-username-in-git
132+
.. _email: https://help.github.com/en/articles/setting-your-commit-email-address-in-git
133+
.. _GitHub account: https://github.com/join
134+
.. _Fork: https://github.com/pallets/flask/fork
135+
.. _Clone: https://help.github.com/en/articles/fork-a-repo#step-2-create-a-local-clone-of-your-fork
136+
137+
138+
Start coding
139+
~~~~~~~~~~~~
140+
141+
- Create a branch to identify the issue you would like to work on. If
142+
you're submitting a bug or documentation fix, branch off of the
143+
latest ".x" branch.
144+
145+
.. code-block:: text
146+
147+
$ git checkout -b your-branch-name origin/2.x
148+
149+
If you're submitting a feature addition or change, branch off of the
150+
"master" branch.
151+
152+
.. code-block:: text
153+
154+
$ git checkout -b your-branch-name origin/master
155+
156+
- Using your favorite editor, make your changes,
157+
`committing as you go`_.
158+
- Include tests that cover any code changes you make. Make sure the
159+
test fails without your patch. Run the tests as described below.
160+
- Push your commits to your fork on GitHub and
161+
`create a pull request`_. Link to the issue being addressed with
162+
``fixes #123`` in the pull request.
163+
164+
.. code-block:: text
165+
166+
$ git push --set-upstream fork your-branch-name
167+
168+
.. _committing as you go: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes
169+
.. _create a pull request: https://help.github.com/en/articles/creating-a-pull-request
170+
171+
172+
Running the tests
173+
~~~~~~~~~~~~~~~~~
174+
175+
Run the basic test suite with pytest.
176+
177+
.. code-block:: text
178+
179+
$ pytest
180+
181+
This runs the tests for the current environment, which is usually
182+
sufficient. CI will run the full suite when you submit your pull
183+
request. You can run the full test suite with tox if you don't want to
184+
wait.
185+
186+
.. code-block:: text
187+
188+
$ tox
189+
190+
191+
Running test coverage
192+
~~~~~~~~~~~~~~~~~~~~~
193+
194+
Generating a report of lines that do not have test coverage can indicate
195+
where to start contributing. Run ``pytest`` using ``coverage`` and
196+
generate a report.
197+
198+
.. code-block:: text
199+
200+
$ pip install coverage
201+
$ coverage run -m pytest
202+
$ coverage html
203+
204+
Open ``htmlcov/index.html`` in your browser to explore the report.
205+
206+
Read more about `coverage <https://coverage.readthedocs.io>`__.
207+
208+
209+
Building the docs
210+
~~~~~~~~~~~~~~~~~
211+
212+
Build the docs in the ``docs`` directory using Sphinx.
213+
214+
.. code-block:: text
215+
216+
$ cd docs
217+
$ make html
218+
219+
Open ``_build/html/index.html`` in your browser to view the docs.
220+
221+
Read more about `Sphinx <https://www.sphinx-doc.org/en/stable/>`__.

‎README.rst

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ Flask-SQLAlchemy is an extension for `Flask`_ that adds support for
66
with Flask by providing useful defaults and extra helpers that make it
77
easier to accomplish common tasks.
88

9+
.. _Flask: https://palletsprojects.com/p/flask/
10+
.. _SQLAlchemy: https://www.sqlalchemy.org
11+
912

1013
Installing
1114
----------
@@ -16,6 +19,8 @@ Install and update using `pip`_:
1619
1720
$ pip install -U Flask-SQLAlchemy
1821
22+
.. _pip: https://pip.pypa.io/en/stable/quickstart/
23+
1924

2025
A Simple Example
2126
----------------
@@ -42,14 +47,30 @@ A Simple Example
4247
users = User.query.all()
4348
4449
50+
Contributing
51+
------------
52+
53+
For guidance on setting up a development environment and how to make a
54+
contribution to Flask-SQLAlchemy, see the `contributing guidelines`_.
55+
56+
.. _contributing guidelines: https://github.com/pallets/flask-sqlalchemy/blob/master/CONTRIBUTING.rst
57+
58+
59+
Donate
60+
------
61+
62+
The Pallets organization develops and supports Flask-SQLAlchemy. In
63+
order to grow the community of contributors and users, and allow the
64+
maintainers to devote more time to the projects, `please donate today`_.
65+
66+
.. _please donate today: https://palletsprojects.com/donate
67+
68+
4569
Links
4670
-----
4771

4872
- Documentation: https://flask-sqlalchemy.palletsprojects.com/
4973
- Releases: https://pypi.org/project/Flask-SQLAlchemy/
5074
- Code: https://github.com/pallets/flask-sqlalchemy
5175
- Issue tracker: https://github.com/pallets/flask-sqlalchemy/issues
52-
53-
.. _Flask: https://palletsprojects.com/p/flask/
54-
.. _SQLAlchemy: https://www.sqlalchemy.org
55-
.. _pip: https://pip.pypa.io/en/stable/quickstart/
76+
- Official chat: https://discord.gg/t6rrQZH

0 commit comments

Comments
 (0)