Contribution Guidelines¶
We use Github projects to organize our ticket workflow. If you want to lend a hand, check out the current project and choose one of the tickets from the issues! If there’s a particular issue you would like to work on and it isn’t already assigned, leave a comment on that issue indicating your desire to work on it. Then, start working!
Start Developing¶
To get started with your contribution, fork this project into your own GitHub profile and clone that forked repository to your machine.
git clone https://github.com/your-username/django-graph-api.git
After cloning, navigate into the new directory.
cd django-graph-api
Define a remote repository called upstream
that points to the original django-graph-api repository.
git remote add upstream https://github.com/django-graph-api/django-graph-api.git
We’re using pipenv as the package and environment manager for this project. If you don’t yet have it, check the link just given for instructions on how to get it on your machine.
(Note for Windows users: The py
launcher cannot tell pipenv
which Python version to use.
The simplest fix is to add to your path only the desired Python folder and its Scripts
subfolder,
then use the commands as shown here without py
.)
Create a pipenv
virtual environment using Python 3.6.
Note: any code that you write should be compatible with Python 2.7, but we recommend that you develop in Python 3.6.
pipenv --python 3.6
Install production dependencies, and also install development-only dependencies:
pipenv install
pipenv install --dev
Verify that the existing tests pass:
pipenv run pytest
(Note that if you have already activated the environment,
which you’ll do in the next section,
you can run the pytest
command on its own to run the tests.)
After you see that those tests pass, activate the virtual environment that pipenv
set up for you and get to work!
Running the Test Project¶
Django Graph API comes with a sample Django project based on the Star Wars examples from GraphQL documentation. It is used for integration tests and to help with development.
If you have installed the local version of django-graph-api
,
then you should already have access to the source code that contains the test data.
To activate the environment:
pipenv shell
Then apply the existing migrations to create a sqlite
database in your repository root.
python manage.py migrate
Create the test data to fill the database
python manage.py create_test_data
Run the test server
python manage.py runserver
You should be able to see the GraphiQL app and run queries by navigating to localhost:8000/graphql
in your browser.
Continue to verify that the tests that you write for your code (as well as the existing tests) pass as you develop by running:
pytest
Building the Documentation¶
Any change you make should correspond with a documentation update. To view your changes in HTML format, you can build the documentation on your computer as follows.
If you haven’t already, create an environment and install the production and development requirements. (Do not redo this if you have already done it – it will delete and re-create your environment.)
pipenv --python 3.6
pipenv install
pipenv install --dev
Navigate to the docs
directory, and build the docs files as html”
cd docs
make html
View the docs by opening _build/html/index.html
in your browser.
Integrating Your Changes¶
Once you’re done writing code, you will need to open a pull request with your changes. In order to be merged, pull requests must fulfill the following requirements:
- All new code must have tests.
- All tests must be passing.
- Any relevant documentation has been updated.
Once your pull request is complete, one of the core contributors will review it and give feedback or merge as appropriate.
Asking for Help¶
If you need help with something, that’s totally fine. Do what you can and then ask for what you need! A good place to ask for help is on the issue that you’re attempting to tackle; leave a comment with the question that you’ve got and what you’ve attempted thus far. Be aware that there may be a delay before someone comes along who has time to provide assistance.
If you have any questions or want to start contributing, chat with us on Slack.
Code of conduct¶
This project adheres to and supports the Django Code of Conduct.
Style guide¶
This project uses the Django coding style guide.