Welcome to Project OSUS, an open-source URL shortener initiative built with Flask, Python, and MongoDB! This project is part of Hacktoberfest 2024, and we're inviting contributions from everyone, whether you're a techie or not.
The goal of this project is to create a simple and efficient URL shortener while fostering learning and collaboration. Contributions can be technical (code) or non-technical (documentation, design), and we encourage everyone to get involved!
- What is HacktoberFest
- About the Project
- Tech Stack
- Live Demo
- Getting Started
- Contributing
- License
- Contact
Hacktoberfest is an annual event celebrated in October, organized by DigitalOcean, GitHub, and other partners, to encourage open-source contributions. During this month, developers of all skill levels are invited to contribute to open-source projects, celebrate their achievements, and connect with the community.
You get to enhance your coding and collaboration skills, connect with like-minded developers and industry professionals and get some recognition and prizes too :)
Important Note: Make sure you've registered in Hacktoberfest website with your Github account. This will track your contributions for the event and ensure you receive your rewards.
Project OSUS is a URL Shortener that allows users to generate shortened URLs that redirect to longer URLs. The project is built with Flask (Python) on the backend and MongoDB for data storage.
Whether you’re a developer, writer, designer, or tester, there are various ways to contribute and learn through this open-source project.
-
Long URL: The user inputs a long URL, for example:
https://www.reddit.com/r/ProgrammerHumor/comments/m7xi4j/should_i_contribute_or_work_on_kaggle/ -
Short URL: The system generates a short URL, for example:
https://project-osus.vercel.app/memeclick here
When users visit the short URL, they are automatically redirected to the original long URL. This makes it easy to share and manage links efficiently.
- Backend: Flask (Python)
- Database: MongoDB
- Frontend: HTML, CSS, JS (with flexibility to improve)
- Version Control: Git/GitHub
🚀 All the changes you contribute will go live on our official website:
https://project-osus.vercel.app/
This means that every improvement you make, whether it's fixing bugs, adding features, or refining the user interface, will be reflected in the live application for everyone to use.
Your contributions will help make Project OSUS better for the community, and you'll get the satisfaction of seeing your work in action!
Ready to make an impact? Start contributing today and watch your work go live! 🌟
Here’s how to get the project running on your local machine.
Make sure you have the following installed on your system:
- Python
- MongoDB (Local installation or Cloud version)
- Git (for version control)
-
Fork the Repository: First, fork the repository to create a personal copy in your GitHub account.
-
Clone the Repository: Clone your forked repository to your local machine using the command:
git clone https://github.com/your-username/repo-name.git
-
Create a virtual environment (optional but recommended):
python -m venv venv source venv/bin/activate # Linux/macOS venv\Scripts\activate # Windows
-
Install dependencies:
pip install -r requirements.txt
-
Create a
.envfile: In the root directory of your project, create a file named.envand add the following environment variables to the file:MONGO_PATH='localhost' MONGO_PORT=27017
Note: If you are using a cloud version of MongoDB, make sure to change MONGO_PATH to your cloud connection string. The connection string format typically looks like this: mongodb+srv://myUser:myPassword@ cluster0.mongodb.net/
-
Start MongoDB (if running locally):
mongod
-
Run the Flask development server:
flask run
-
The project will be running at
http://localhost:5000. Visit that in your browser to start using the URL shortener!
We encourage contributions from everyone! Whether you're looking to contribute code, documentation, design, or testing, here's how you can get involved.
-
Fork the repository:
- Go to the main repository page and click on the "Fork" button in the top right corner.
-
Raise an issue:
- Before starting to work on a new feature or bug fix, check if there’s an existing issue related to it. If not, open a new issue.
- If you're working on an existing issue, leave a comment on that issue thread saying you're working on it to avoid duplicating efforts.
-
Create a new branch:
- Create a branch for your contribution. Use a descriptive name for your branch, such as
fix-issue-#numberoradd-new-feature:git checkout -b branch-name
- Create a branch for your contribution. Use a descriptive name for your branch, such as
-
Make your changes:
- Make sure your code follows the project structure and use autopep8 for code formatting to ensure consistency:
-
Commit your changes:
- Write a meaningful commit message describing your changes:
git add . git commit -m "Description of your changes"
- Write a meaningful commit message describing your changes:
-
Push to your forked repository:
git push origin branch-name
-
Create a pull request (PR):
Once your changes are pushed, come back to this repository on GitHub. You should see a prompt to create a pull request (PR). Click on it and fill in the details about your changes, explaining why you made them.
And that's it! You have successfully made your contribution. The maintainers will review your PR and provide feedback or merge it if everything looks good.
- Bug Fixes: Find and fix bugs to improve the project.
- Feature Enhancements: Add new features, such as custom URLs, user authentication, or analytics.
- Code Quality: Refactor and improve code quality or performance.
- UI/UX: Help improve the front-end design or overall user experience.
- Documentation: Improve this README or create new guides for contributors.
- Testing: Write test cases or help test the project for bugs.
- Design: Create graphics, logos, or improve the UI design.
This project is licensed under the MIT License. See the LICENSE file for more details.
Got questions, or need help or you want to help maintainers?? Feel free to reach out via issues or via:
