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. Here are some resources which might help you:

Resources

Please see the Education section to see what you need to learn before contributing.

Setup Instructions

If you want to contribute, go ahead, we ❤️ it. We follow a 💯 % first-timers-friendly policy.

  1. Make sure git is installed on your computer and python version 3.6 or higher is installed (we recommend python 3.9). You can run the following command to check if git is installed and which python version you have. If either commands gives error then it means you need to install that software

    git --version
    python --version
    
  2. Fork repo. To do so go to the shopyo repo and press the fork button

  3. Clone the repo by running:

    git clone https://github.com/<replace with your github username>/shopyo.git.
    

    Note

    You can also get the clone link by clicking the green code button on your cloned shopyo repo page.

  4. Next run:

    cd <your/local/cloned/repo/path/here>
    

    Note

    The above command should be cd shopyo if you cloned using the git command above

  5. Setup the python virtual environment based on your Operating System

    For Windows OS you can do this by running:

    py -m pip install --upgrade pip
    py -m venv env # you can replace env with another name that you like. For example, py -m venv shopyo-env
    

    For Linux and MacOS you can do this by running:

    python3 -m pip install --user --upgrade pip
    python3 -m venv env # you can replace env with another name that you like. For example, python3 -m venv shopyo-env
    

    Note

    visit virtual environment for more details

  6. Activate the virtual environment as follows:

    For Windows OS you can do this by running:

    .\env\Scripts\activate
    

    For Linux and MacOS you can do this by running:

    source env/bin/activate
    

    Now you should see something like:

    (env) </my/path/to/shopyo>
    

    Note

    env is the name of virtual environment that you setup in step 5 above. Make sure to always activate this env when working on shopyo. If you are using VS Code then you can also add the "python.pythonPath" by creating a .vscode folder at the root level and adding settings.json file to it with the content below. You need to replace the path with your own path to the virtual environment’s python.exe You can copy the below json to settings.json file depending on your OS. Now you can create a new terminal with virtual environment activated in VS Code using Ctrl + Shift + ` (control plus shift plus backtick character). In addition, if you want to deactivate the virtual environment, run deactivate in command line

    For Windows OS:

    {
       "python.pythonPath": "${workspaceFolder}/env/Scripts/python.exe"
    }
    

    For Unix/MacOS

    {
       "python.pythonPath": "${workspaceFolder}/env/bin/python"
    }
    
  7. Run:

    python -m pip install -U pip
    python -m pip install -e .
    python -m pip install -r requirements/dev.txt
    

    Note

    This should start installing the packages required for shopyo app and might take a few seconds.

  8. Setup pre-commit to make sure the style is consistent

    pre-commit install
    
  9. Next we need to setup an upstream which will allow you to update your local shopyo repo to match the owner’s shopyo repo in case of any changes. You only need to do this once. To setup an upstream you do:

    cd <your/local/cloned/repo/path/here> # not needed if you are already inside your cloned shopyo directory
    git remote add upstream https://github.com/shopyo/shopyo
    
  10. Once upstream is setup, you can fetch the latest changes made to shopyo repo. Make sure to do this every time before you make branch to work on a feature. Run:

    git fetch upstream
    git pull upstream dev
    
  11. Now initialize the app by running:

    cd shopyo
    # so now your path should be something like <your path>/shopyo/shopyo
    shopyo initialise
    

    Note

    The above initialise command can also be run as follows:

    python manage.py initialise
    
  12. To start the app, run:

    python manage.py rundebug
    
  13. The app should now be running on IP 127.0.0.1 at port 5000. You can go to http://localhost:5000/ or http://127.0.0.1:5000/. For the home page it will say SITE UNDER CONSTRUCTION. Go to http://localhost:5000/login/. Login with email admin@domain.com and password pass

Making a Pull Request

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

  1. Let say you are excited about a feature you want to work on. You need to first create a separate branch and work on that branch. To check which branch you are currently on run git branch. Most likely you will see dev branch colored green or marked to tell you that you are on dev branch. Before creating a new branch from dev make sure you have fetched latest changes as mentioned in Setup Instructions step 10

  2. To create a branch and switch to that branch you run:

    git checkout -b <name of branch>
    # example: git checkout -b add-form-validation
    

    Note

    You can do the above using 2 separate commands if that makes it easier:

    # First create a new branch from current branch
    git branch <name of branch>
    
    # Next switch to this new branch
    git checkout <name of branch to switch to>
    
  3. After git checkout command above, run git branch to make sure you are not working on dev branch but are on the newly created branch.

  4. Now you can start working on the feature for which you want to make PR

  5. Add tests for any new features that you add.

  6. Run the following to make sure all the existing and new tests pass. Check the Testing section for more details

    python -m pytest .
    
  7. [Optional Step] Make sure to bump the version number in file shopyo/__init__.py as follows:
    • small fixes: _._.x, (example 3.4.6 to 3.4.7)

    • feature, many fixes etc: _.x.0, (example 3.4.6 to 3.5.0)

    • big feature, breaking change etc x.0.0 (example 3.4.6 to 4.0.0)

  8. Check that there are no linting errors according to flake8. To do so you can run

    flake8 <path of file that you want to check>
    
    # example to check the linting error for test_dashboard.py file
    # assuming you are in shopyo/shopyo directory, run
    flake8 ./modules/box__default/dashboard/tests/test_dashboard.py
    

    Note

    If the command above returns without any output, then there are no linting errors, otherwise it will tell you the line number and type of linting error. If typing flake8 gives error related to command not found, then you do not have flake8 installed and it can be installed as follows:

    python -m pip install flake8
    

    In addition, if you are using VS Code then you can create a .vscode folder at the root level and add settings.json file to it with the following content. This way it auto detects the linting errors for you

    {
       "python.linting.flake8Enabled": true
    }
    

    If you have already created the settings.json file as mentioned in Setup Instructions step 5, then your json file will look similar to one below

    For Windows OS:

    {
       "python.pythonPath": "${workspaceFolder}/env/Scripts/python.exe",
       "python.linting.flake8Enabled": true
    }
    

    For Unix/MacOS

    {
       "python.pythonPath": "${workspaceFolder}/env/bin/python",
       "python.linting.flake8Enabled": true
    }
    
  9. Once you are happy with the changes you made you can double check the changed files by running:

    git status
    
  10. Next add the changes as required

    git add . # to add all changes
    git add <file1 name> <file2 name> # to only add desired files
    
  11. Commit the changes. For the commit messages, follow the guidelines here

    git commit -m "<put your commit message here>"
    
  12. Finally push the committed changes from local repository to a remote repository (the one you forked)

    git push origin <the current branch name>
    
  13. You can now make a PR. When you go to your forked repo or the owner’s repo you will see a compare & pull request button. Click on it and mention the changes you made. Look at the past PRs for examples of what to mention when submitting a PR. If a PR closes an issue, add Fixes #<issue number>, as seen here

  14. [Optional Step] If you want you can request reviews when submitting PR.

  15. [Optional Step] Add your country flag in readme after accepted PR.

Note

At times when you do git status after fetching the latest changes it might say something like: Your branch is ahead of 'origin/dev which mean that your forked branch does not have the latest local changes and does not match the owner’s repo. To push the latest changes to your forked repo, run:

git push origin head

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:

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

  • run pip install -e . # if you did not

  • test shopyo <your options>

If you want a system wide tests run python setup.py sdist then python -m pip install path/to/shopyo-x.x.x.tar.gz where shopyo-… is found in dist/

Maintainers notes

  • Version is found in shopyo/__init__.py

1
2
# from shopyo.app import create_app

  • to publish to pypi, run

python setup.py publish

In __main__.py don’t forget to update dev_requirements.txt

💬 Community: Discord

Join the Discord community Discord Group