Skip to content

Latest commit

 

History

History
166 lines (108 loc) · 6.73 KB

CONTRIBUTING.md

File metadata and controls

166 lines (108 loc) · 6.73 KB
Raw

How to contribute

We appreciate all pull requests. However, before working on an enhancement/feature, you should:

  • Search to see if there's already a discussion on the Issue Tracker. If not, you should start a new discussion
  • Let us know you're working on the issue, so that we can (1) help fill in any gaps in the requirements, and (2) avoid having multiple contributors do redundant work

Table of Contents

Local Development

Requirements

To perform local development, you'll need:

  • Python 3.7+
  • pip
  • virtualenv
  • node
  • npm
  • libmemcached for using an external memcached in-memory cache. Install on MacOSX Homebrew with brew install libmemcached. If you do not want to enable external caching during deployment, you can skip this requirement. However, you will have to exclude pylibmc from requirements.txt before installing the project Python requirements.

To create your own deployment on Heroku, you may also want the Heroku Toolbelt.

Building

Clone the repository and switch to the project directory:

git clone https://github.com/twschiller/open-synthesis.git
cd open-synthesis

Create a project-specific package environment using virtualenv:

virtualenv venv

Switch to the virtualenv. On Windows, run this command:

venv\Scripts\activate.bat

On Mac/Linux, run this command:

source venv/bin/activate

Install the project requirements:

pip install -r requirements.txt
npm install

Create a local environment configuration by copying the defaults in env.sample:

cp env.sample .env

Package the static files for the project:

npm run build
python manage.py collectstatic

Run the test suite to ensure your environment is properly configured:

pytest

Create the database schema, and load the initial application data:

python manage.py migrate
python manage.py loaddata source_tags

Web Server

To run the Django development server, which automatically reloads modules when you edit a file:

python manage.py runserver

To serve the Django application using Gunicorn:

gunicorn -c conf.py openintel.wsgi --log-file -

If you are using Heroku, you can also run the Gunicorn server with:

heroku local web

Celery Task Runner

If you have a local instance of Redis, you can configure Celery to use it as broker/result store by setting REDIS_URL and CELERY_ALWAYS_EAGER in the .env file:

REDIS_URL=redis://localhost:6379
CELERY_ALWAYS_EAGER=False

Then run the Celery worker:

celery worker --app=openintel.celery.app

If you are using Heroku, you can also run the worker with:

heroku local worker

Code Style and Testing

Before submitting a pull request, please review the quality control wiki.

Adding a Translation

If you want to help translate Open Synthesis but don't want to set up local development environment, let us know and we'll assist you.

First, if you haven't already, follow the instructions above to set up your local development environment. Next, install GNU gettext. If you're using Homebrew, the following commands install and link gettext:

brew install gettext
brew link --force gettext

Create a translation file for your locale with the makemessages command. A list of language codes is available here. For example, to create a British English translation, use the following command:

python manage.py makemessages --locale=en_GB

This will create a folder for the locale in the locale directory with a messages file django.po. Translate the messages by filling in the msgstr fields in the messages file.

Compile the translations with the compilemessages command:

python manage.py compilemessages

Add your translation to the openintel/settings.py file. Note that the language corresponding to the locale is lower case and uses a hyphen - instead of an underscore _. So locale en_GB becomes en-gb:

LANGUAGES = (
    ('en', _('English (United States)')),
    ('en-gb', _('English (British)')),
)

Your translation should now be available when you restart your server. If you're still seeing English, double-check that your browser is requesting the page in the language you created.

Acknowledgements

Contributors

Third-Party Libraries and Services

We gratefully acknowledge this project's third-party libraries and their contributors. See here and here. Additionally, we'd like to acknowledge the following: