Contributing Guidelines
First off, thank you for considering contributing to this project! It's people like you that make the open source community such a fantastic place to learn, inspire, and create. Every contribution helps and is greatly appreciated!
In this document, you will find guidelines and directions for contributing to this project. Please respect these guidelines as they are meant to foster a consistent and respectful approach to collaboration.
π Table of Contents
- π Code of Conduct
- π‘ How Can I Contribute?
- πͺ² Reporting Bugs
- β¨ Suggesting Enhancements
- π₯ Pull Requests Guidelines
- ποΈ Project Structure
- π Pre-requisites
- π Getting started
- π¨ Styleguides
- π οΈ Basic Jinja2 Templating Engine introduction
- βπ» Writing Blog Posts and Tutorials
π Code of Conduct
This project and everyone participating in it is governed by the Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to support@spoo.me.
π‘ How Can I Contribute?
You can contribute to this project in many ways. Here are a few ideas:
- Reporting bugs and issues on GitHub πͺ²
- Suggesting enhancements and new features on GitHub β¨
- Fixing bugs and issues by submitting pull requests π οΈ
- Implementing new features
- Improving the documentation π
- Sharing the project with others π£
- Providing support to other people who are using the project π€
- Writing blog posts and tutorials βπ»
We are always available to help you with your contribution. If you are unsure about anything, just ping us on discord server. We will be happy to help you.
πͺ² Reporting Bugs
Before creating bug reports, please check the existing bug reports as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible.
β¨ Suggesting Enhancements
Before creating enhancement suggestions, please check the existing suggestions as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please include as many details as possible.
π₯ Pull Requests Guidelines
The process described here has several goals:
- Maintain the project's quality
- Fix problems that are important to users
- Engage the community in working toward the best possible project
- Enable a sustainable system for the project's maintainers to review contributions
Please follow these steps to have your contribution considered by the maintainers:
- Follow all instructions in the template
- Adhering to the project's code of conduct
- Follow the styleguides
- After you submit your pull request, verify that all status checks are passing
- After you create a pull request, maintainers will review your proposal and discuss it with you
ποΈ Project Structure
The project is structured as follows:
url-shortener/
β .env
β .env.example
β .gitignore
β contributing.md
β docker-compose.yml
β dockerfile
β emojies.py
β LICENSE
β main.py
β README.md
β requirements.txt
β utils.py
β vercel.json
ββββ.github
β ββββworkflows
β api_test.yaml
β format.yaml
ββββmisc
ββββblueprints
β | api.py
β | contact.py
β | docs.py
β | limiter.py
β | seo.py
β | stats.py
β | url_shortener.py
ββββstatic
β ββββcss
β β api.css
β β base.css
β β confetti.css
β β contacts-modal.css
β β error.css
β β header.css
β β index.css
β β mobile-header.css
β β password.css
β β prism-duotone-dark.css
β β result.css
β β self-promo.css
β β stats-view.css
β β stats.css
β ββββimages
β ββββjs
β β confetti.js
β β contacts-popup.js
β β header.js
β β index-qrcode.js
β β index-script.js
β β index-validate.js
β β result-script.js
β β self-promo.js
β β stats-script.js
β β stats-view-script.js
β ββββpreviews
ββββtemplates
β api.html
β error.html
β index.html
β password.html
β result.html
β stats.html
β stats_view.html
ββββtests
shorten.py
stats.py
π Pre-requisites
- Python 3.9 or higher
- pip
- virtualenv
- MongoDB
- Basic knowledge of Python, HTML, CSS, and JavaScript
- Basic knowledge of jinja2 templating engine; more information on this can be found in the Basic Jinja2 Templating Engine introduction section
- Basic knowledge of MongoDB
If you are just here to contribute to the frontend, having knowledge of Python and MongoDB is not necessary.
You need to have MongoDB installed on your machine to run the project. You can download it from here. Or you can also use Instant MongoDB extension available for Visual Studio Code.
π Getting started
Fork the repository on GitHub
- Clone the project to your own machine
- Install the project dependencies
- Create a new branch
- Creating .env file
-
Starting the development server
-
Creating a new virtual environment
python -m venv venv
-
Activating the virtual environment
source venv/bin/activate
-
Running the development server
python app.py
-
-
You can access the development server at:
http://127.0.0.1:8000/
-
Make your changes
Note: If you made some changes in the static Files, you need to update the version of the static file in the static file import syntax of the HTML files. For example, if you made some changes in the
style.css
file, you need to update the version of thestyle.css
file in theindex.html
file. You can do this by adding a query parameter to the end of the file name.For example:
<link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}?v=1"/>
If the version of the file is already updated, you can just change the value of the query parameter to the next number. For example,
<link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}?v=2"/>
More information on how to do this can be found in the Basic Jinja2 Templating Engine introduction section.
Format your code, more information on how to do this can be found in the Styleguides section
Commit your changes
Check if all of the workflow checks are passing
Push your branch to your fork
git clone https://github.com/spoo-me/url-shortener.git
cd url-shortener
pip install -r requirements.txt
git checkout -b my-new-branch
touch mv .env.example .env
π¨ Styleguides
For the sake of consistency and maintainability, we have a few styleguides that we follow. Please adhere to these guidelines when contributing to the project.
π¬ Git Commit Messages
-
Use the present tense ("Add feature" not "Added feature")
-
Use the imperative mood ("Move cursor toβ¦" not "Moves cursor toβ¦")
-
Limit the first line to 72 characters or less
-
Reference issues and pull requests liberally after the first line
-
Consider starting the commit message with an applicable emoji:
-
π when adding a new feature
-
π¨ when improving the format/structure of the code
-
π when improving performance
-
π when writing docs
-
π when fixing a bug
-
π₯ when removing code or files
-
π when dealing with security
-
β¬οΈ when upgrading dependencies
-
β¬οΈ when downgrading dependencies
π Python Styleguide
All Python code should be formatted using the black code formatter. This ensures that all code is formatted consistently and makes it easier to review and maintain. We have a workflow that automatically checks for code formatting and will fail if the code is not formatted correctly.
How to Install Black:
pip install black
How to Use Black:
python -m black *.py
π Html, css and Javascript Styleguide
All HTML and CSS code should be formatted using the prettier code formatter. This ensures that all code is formatted consistently and makes it easier to review and maintain.
π οΈ Basic Jinja2 Templating Engine introduction
Jinja2 is a modern and designer-friendly templating language for Python, modelled after Djangoβs templates. It is fast, widely used and secure with the optional sandboxed template execution environment.
Files are stored in the templates
directory and the static files are stored in the
static
directory. The templates
directory contains the HTML files and the
static
directory contains the CSS, JavaScript, and images.
The HTML files are rendered using the Jinja2 templating engine. The Jinja2 templating engine uses the
{{ }}
syntax to render variables and the
{% %}
syntax to render control
statements.
For example, the following code will render the title
variable sent by the server in the HTML
file:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1.0"
/>
<title>{{ title }}</title>
</head>
<body>
<h1>{{ title }}</h1>
</body>
</html>
Separating the static files from the HTML files makes the project more organized and easier to
maintain. The static files are included in the HTML files using the url_for
function. The
url_for
function takes the name of the static file as an argument and returns the URL of
the static file.
For example, the following code will include the style.css
file in the HTML file:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1.0"
/>
<link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}"/>
</head>
<body>
<h1>{{ title }}</h1>
</body>
</html>
In the above example, the url_for
function takes the name of the folder where the static file is
stored and the name of the static file as arguments and returns the URL of the static file. In this project
the static files are stored in the static
folder and the style.css
file is stored
in the css
folder.
The url_for
function is the only way to include static files in the HTML files. You can also add
inline CSS and JavaScript in the HTML files but it is not recommended.
In order to add local images in the HTML files, you can use the url_for
function. For example,
the following code will include the logo.png
file in the HTML file:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1.0"
/>
</head>
<body>
<img src="{{ url_for('static', filename='images/logo.png') }}" alt="Logo"/>
</body>
</html>
IMPORTANT STEP:
If you made some changes in the static files, you need to update the version of the static file in the static
file import syntax of the HTML files. For example, if you made some changes in the style.css
file, you need to update the version of the style.css
file in the index.html
file.
You can do this by adding a query parameter to the end of the file name.
For example:
<link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}?v=1"/>
If the version of the file is already updated, you can just change the value of the query parameter to the next number. For example,
<link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}?v=2"/>
DOING THIS IS REALLY IMPORTANT AS VERCEL CACHES THE STATIC FILES AND IF YOU DON'T UPDATE THE VERSION OF THE STATIC FILES, THE CHANGES YOU MADE IN THE STATIC FILES WILL NOT BE REFLECTED IN THE PRODUCTION SERVER.
Important Notes:
- The
url_for
function is a Jinja2 function and can only be used in the HTML files. - If you added some new static files, you need to add those files in the
static/<file_type>
directory and then include them in the HTML files using theurl_for
function. - The
{{ }}
syntax is used to render variables in HTML files only. These variables are sent by the server. They cannot be accessed in the static files. - The
{% %}
syntax is used to render control statements in HTML files only. These control statements are used to control the flow of the HTML file. They cannot be accessed in the static files. - If you are here to contribute to the frontend, you don't need to worry about the html variables and control statements. You just need to focus on the static files. Although, it is recommended to have a basic understanding of the Jinja2 templating engine incase you want to change the structure of the HTML files.
Take a look at the Jinja2 documentation for more information.
βπ» Writing Blog Posts and Tutorials
If you are interested in writing blog posts and tutorials, you can talk to us on Discord or send us an email at admin@spoo.me