Contributing to Shopyo — Shopyo documentation

# 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

   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 `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` + ``` (control plus shift plus backtick character). In addition, if you want to deactivate the virtual environment, run `deactivate` in command line

       {
          "python.pythonPath": "c:\\path\\to\\shopyo\\env\\Scripts\\python.exe"
       }

7. Change into the directory:

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

8. Run:

       python -m pip install -U pip
       python -m pip install -e .
       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.

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/Abdur-rahmaanJ/shopyo.git

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
        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/. 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 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 `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. [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
    version_info = (3, 9, 0)
    __version__ = ".".join([str(v) for v in version_info])

- 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