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


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:

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:

Please follow these steps to have your contribution considered by the maintainers:

  1. Follow all instructions in the template
  2. Adhering to the project's code of conduct
  3. Follow the styleguides
  4. After you submit your pull request, verify that all status checks are passing
  5. 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


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


  1. Fork the repository on GitHub

  2. Clone the project to your own machine
  3. git clone https://github.com/spoo-me/url-shortener.git
    cd url-shortener
    
  4. Install the project dependencies
  5. pip install -r requirements.txt
    
  6. Create a new branch
  7. git checkout -b my-new-branch
    
  8. Creating .env file
  9. touch mv .env.example .env
    
  10. 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
      
  11. You can access the development server at: http://127.0.0.1:8000/

  12. 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.

  13. Format your code, more information on how to do this can be found in the Styleguides section

  14. Commit your changes

  15. Check if all of the workflow checks are passing

  16. 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



🐍 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:

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