Contributing to Shopyo

Shopyo is built using Flask but mimicks 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. 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

  6. Activate the virtual environment. Now you should see something like:

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

    Note

    env is the name of virtual environment that you setup in step 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 setting.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 file and the example below is for a path in Windows OS hence the double backward slash. Now you can create a new terminal with virtual environment activated in VS Code using Ctrl + Shift + `

    {
       "python.pythonPath": "c:\\Users\\user\\Documents\\venvs\\my-shopyo-env\\Scripts\\python.exe"
    }
    
  7. Run:

    python -m pip install -r dev_requirements.txt
    

    Note

    This should start installing the packages required for shopyo app and might take a few seconds. If you get an error for unable to find dev_requirements.txt make sure you are in the cloned shopyo directory and try again

  8. 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/Abdur-rahmaanJ/shopyo.git
    
  9. 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
    
  10. Do another:

    cd shopyo
    # so now your path should be something likes <your path>/shopyo/shopyo
    
  11. Now initialize the app by running:

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

    python manage.py runserver
    
  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/ (127.0.0.1 is another name for localhost). You can click the login nav link or go directly 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 9

  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. 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 setting.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 setting.json file as mentioned in Setup Instructions step 6, then your json file will look similar to one below

    {
       "python.pythonPath": "c:\\Users\\user\\Documents\\venvs\\my-shopyo-env\\Scripts\\python.exe",
       "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. If you want you can request reviews when submitting PR.

  15. Add your country flag in readme after accepted PR

  16. 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 the forked branch does not have the latest changes. To push the latest changes to your forked repo, run:

    git push origin head
    

Contributing to package

  • clone project

  • cd into project folder

  • create and activate venv

  • run pip install -e .

  • after changes run pip install -e . --upgrade

  • test shopyo <your options>

Maintainers notes

  • Version is found in shopyo/__init__.py

1
__version__ = ".".join([str(v) for v in version_info])
  • to publish to pypi, run

python setup.py publish

💬 Community: Discord

Join the Discord community Discord Group