Contributing to Shopyo#

Shopyo is built using Flask but mimics Django so that you get to use plug and play modules. To contribute, it’s nice to know Flask well.

If you want to contribute, go ahead, we ❤️ it. We follow a 💯 % first-timers-friendly policy. Feel free to join our discord group if you get stuck or would just like to chat and say hi.

This contribution guide has been adopted from the version used by Flask.

First time setup#

  • Download and install the latest version of git.

  • Configure git with your username and email.

    $ git config --global user.name 'your name'
    $ git config --global user.email 'your email'
    
  • Make sure you have a GitHub account.

  • Fork Shopyo to your GitHub account by clicking the Fork button.

  • Clone the main repository locally (make sure to have your SSH authentication setup!)

    $ git clone git@github.com:shopyo/shopyo.git
    $ cd shopyo
    
  • Add your fork as a remote to push your work to. Replace {username} with your username. This names the remote fork. The default Shopyo remote is origin.

    git remote add fork git@github.com:{username}/shopyo.git
    
  • Create a virtualenv and activate the virtual environment:

    $ python3 -m venv env
    $ . env/bin/activate
    
  • Upgrade pip and setuptools:

    $ python -m pip install --upgrade pip setuptools
    
  • Install the development dependencies and Shopyo requirements in editable mode:

    $ pip install -r requirements/dev.txt && pip install -e .
    
  • Install the pre-commit hooks:

    $ pre-commit install
    
  • Now initialize the app by running:

    $ cd shopyo
    $ shopyo initialise
    
  • Check if the shopyo app runs properly:

    $ shopyo rundebug
    
  • Go to the link http://127.0.0.1:5000/ and you should see Shopyo is now running!. Go to http://127.0.0.1:5000/auth/login and then you can access the dashboard by logging in with email admin@domain.com and password pass

Pull Requests#

Make sure you have setup the repo as explained in First time setup before making Pull Request (PR)

  • Create a branch for the issue you would like to work on:

    $ git fetch origin
    $ git checkout -b <your-branch-name> origin/dev
    

    Note

    As a sanity check, you can run git branch to see the current branch you are on in case your terminal is not setup to show the current branch.

  • Make sure to write tests for any new features you add. To run the whole test suite, see the command below. This may take a while. See Testing for useful commands such as to run only the tests that you wrote for example.

    $ tox
    
  • Using your favorite editor, make your changes, committing as you go.

    $ git add <filenames to commit>
    $ git commit -m "<put commit message here>"
    
  • Committing files will run the pre-commit hook, which includes some style checks. In case the checks fail, it will not allow you to commit and mention the errors and their line numbers. Most of the time, the pre-commit hook will automatically fix the style errors so you will need to run the git commit command again. For the example below, after running git commit, the pre-commit for flake8 failed. In this case, remove the unused import in shopyo/app.py and commit again

    $ git commit -m "test commit"
    pyupgrade................................................................Passed
    Reorder Python imports...................................................Passed
    black....................................................................Passed
    flake8...................................................................Failed
    - hook id: flake8
    - exit code: 1
    
    shopyo/app.py:2:1: F401 'json' imported but unused
    
    fix UTF-8 byte order marker..............................................Passed
    Trim Trailing Whitespace.................................................Passed
    Fix End of Files.........................................................Passed
    Check Yaml...........................................(no files to check)Skipped
    Debug Statements (Python)................................................Passed
    Check for added large files..............................................Passed
    
  • Push your commits to your fork on GitHub.

    $ git push --set-upstream fork your-branch-name
    
  • Create a pull request. You should see the PR link in the terminal after you successfully push your commits. Link to the issue being addressed with fixes #123 in the pull request. See example PR.

Use commitizen to commit (experimental)#

Use

$ cz c

to commit and

$ cz changelog

to generate changelog (for maintainers)

Setup Mail Dev Environment (Optional)#

  • If you have Node.js, use the maildev package. Install it using

    $ npm install -g maildev
    
  • Then serve it using

    $ maildev
    
  • Dev configs for this setup are:

    # shopyo/shopyo/config.py
    class DevelopmentConfig(Config):
        """Configurations for development"""
    
        ENV = "development"
        DEBUG = True
        LOGIN_DISABLED = False
        # control email confirmation for user registration
        EMAIL_CONFIRMATION_DISABLED = False
        # flask-mailman configs
        MAIL_SERVER = 'localhost'
        MAIL_PORT = 1025
        MAIL_USE_TLS = False
        MAIL_USE_SSL = False
        MAIL_USERNAME = '' # os.environ.get("MAIL_USERNAME")
        MAIL_PASSWORD = '' # os.environ.get("MAIL_PASSWORD")
        MAIL_DEFAULT_SENDER = 'ma@mail.com' # os.environ.get("MAIL_DEFAULT_SENDER")
    
  • Go to http://127.0.0.1:1080 where it serves it’s web interface by default. See mails arrive in your inbox!

Contributing to package#

  • Install the Shopyo requirements in editable mode if you did not already.

    $ pip install -e .
    
  • Test to see if shopyo cli works. Example run

    $ shopyo --help
    
  • If you want a system wide tests run the following under the Shopyo repository

    $ python setup.py sdist
    $ python -m pip install dist/shopyo-4.1.2.tar.gz
    

Maintainers notes#

  • Version is found in shopyo/__init__.py

1version_info = (4, 9, 3)
2__version__ = ".".join([str(v) for v in version_info])
  • To publish to PyPi, run

python setup.py publish