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:
Setup Instructions¶
If you want to contribute, go ahead, we ❤️ it. We follow a 💯 % first-timers-friendly policy.
Make sure
git
is installed on your computer andpython 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 softwaregit --version python --version
Fork repo. To do so go to the shopyo repo and press the fork button
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.Next run:
cd <your/local/cloned/repo/path/here>
Note
The above command should be
cd shopyo
if you cloned using the git command aboveSetup 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
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 thisenv
when working onshopyo
. If you are using VS Code then you can also add the"python.pythonPath"
by creating a.vscode
folder at the root level and addingsetting.json
file to it with the content below. You need to replace the path with your own path to the virtual environment’spython.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 usingCtrl
+Shift
+`
(control plus shift plus backtick character). In addition, if you want to deactivate the virtual environment, rundeactivate
in command line{ "python.pythonPath": "c:\\path\\to\\shopyo\\env\\Scripts\\python.exe" }
Change into the directory:
cd shopyo # so now your path should be something like <your path>/shopyo
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.
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
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
Now initialize the app by running:
cd shopyo # so now your path should be something like <your path>/shopyo/shopyo python manage.py initialise
To start the app, run:
python manage.py runserver
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 emailadmin@domain.com
and passwordpass
Making a Pull Request¶
Make sure you have setup the repo as explained in Setup Instructions before making Pull Request (PR)
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 seedev
branch colored green or marked to tell you that you are ondev
branch. Before creating a new branch fromdev
make sure you have fetched latest changes as mentioned in Setup Instructions step 10To 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>
After git checkout command above, run
git branch
to make sure you are not working ondev
branch but are on the newly created branch.Now you can start working on the feature for which you want to make PR
Add tests for any new features that you add.
Run the following to make sure all the existing and new tests pass. Check the Testing section for more details
python -m pytest .
- [Optional Step] Make sure to bump the version number in file
shopyo/__init__.py
as follows: small fixes:
_._.x
, (example3.4.6
to3.4.7
)feature, many fixes etc:
_.x.0
, (example3.4.6
to3.5.0
)big feature, breaking change etc
x.0.0
(example3.4.6
to4.0.0
)
- [Optional Step] Make sure to bump the version number in file
Check that there are no linting errors according to
flake8
. To do so you can runflake8 <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 haveflake8
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 addsetting.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 }
Once you are happy with the changes you made you can double check the changed files by running:
git status
Next add the changes as required
git add . # to add all changes git add <file1 name> <file2 name> # to only add desired files
Commit the changes. For the commit messages, follow the guidelines here
git commit -m "<put your commit message here>"
Finally push the committed changes from local repository to a remote repository (the one you forked)
git push origin <the current branch name>
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, addFixes #<issue number>
, as seen here[Optional Step] If you want you can request reviews when submitting PR.
[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 nottest
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