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

git clone https://github.com/spoo-me/url-shortener.git
cd url-shortener

Install the project dependencies

pip install -r requirements.txt

Create a new branch

git checkout -b my-new-branch

Creating .env file

touch mv .env.example .env

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 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"/>
```
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

🎨 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 the url_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

Contribution Charts

Contact Us