📚 doc: Add necessary repository files

Add CONTRIBUTORS,CONTRIBUTING,PYTEST_Guide,SECURITY files

CODE_OF_CONDUCT.md

@@ -1,26 +1,166 @@
-# Code Of Conduct
+## Contribution Guidelines
 
-**Like the technical community as a whole, the Sage team and community is made up of a mixture of professionals, working on every aspect of the mission - including mentorship, teaching, and connecting people.**
+Thank you for your interest in contributing to our package! This document outlines the tools and steps to follow to ensure a smooth and consistent workflow.
 
-* Diversity is one of our huge strengths, but it can also lead to communication issues and unhappiness. To that end, we have a few ground rules that we ask people to adhere to. This code applies equally to founders, mentors and those seeking help and guidance.
+## Contribution Workflow
 
-* This isn’t an exhaustive list of things that you can’t do. Rather, take it in the spirit in which it’s intended - a guide to make it easier to enrich all of us and the technical communities in which we participate.
+1. **Fork and Clone**: Fork the repository and clone it to your local machine.
+    ```bash
+    git clone https://github.com/sageteamorg/django-iranian-cities.git
+    cd django-iranian-cities
+    ```
 
-* if you believe someone is violating the code of conduct, we ask that you report it by emailing [email protected]
+2. **Create a Branch**: Create a new branch for your feature or bugfix.
+    ```bash
+    git checkout -b feature/your-feature-name
+    ```
 
-1. **Be friendly and patient**.
-2. **Be welcoming**. We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability.
-3. **Be considerate**. Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language.
-4. **Be respectful**. Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the Django community should be respectful when dealing with other members as well as with people outside the Django community.
-5. **Be careful in the words that you choose**. We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to:
+3. **Install Dependencies**: Use Poetry to install dependencies.
+    ```bash
+    poetry install
+    ```
 
-- Violent threats or language directed against another person.
-- Discriminatory jokes and language.
-- sexually explicit or violent material.
-- Posting (or threatening to post) other people's personally identifying information ("doxing").
-- Personal insults, especially those using racist or sexist terms.
-- Unwelcome sexual attention.
-- Advocating for, or encouraging, any of the above behavior.
-- Repeated harassment of others. In general, if someone asks you to stop, then stop.
+4. **Write Code and Tests**: Make your changes and write tests for your new code.
 
-6. **When we disagree, try to understand why**. Disagreements, both social and technical, happen all the time and Django is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we’re different. The strength of Django comes from its varied community, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes.
+5. **Run Code Quality Checks**: Ensure code quality with pre-commit, Ruff, and Pylint.
+    ```bash
+    ruff check .
+    ruff check --fix
+    ```
+
+6. **Run Tests**: Ensure all tests pass using Poetry.
+    ```bash
+    poetry run pytest
+    ```
+
+7. **Commit Changes**: Use Commitizen to commit your changes.
+    ```bash
+    cz commit
+    ```
+
+8. **Push and Create a PR**: Push your changes and create a pull request.
+    ```bash
+    git push origin feature/your-feature-name
+    ```
+
+9. **Bump Version**: Use Commitizen to bump the version.
+    ```bash
+    cz bump
+    ```
+
+10. **Generate Changelog**: Use Commitizen to generate the changelog.
+    ```bash
+    cz changelog
+    ```
+
+11. **Export Dependencies**: Export dependencies for development and production.
+    ```bash
+    poetry export -f requirements.txt --output packages/requirements.txt --without-hashes
+    poetry export -f requirements.txt --dev --output packages/requirements-dev.txt --without-hashes
+    ```
+
+## Commitizen Message Rule
+
+Commitizen follows the Conventional Commits specification. The commit message should be structured as follows:
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Here are 10 examples of commit messages following the Commitizen Conventional Commits specification:
+
+### 1. Initialization of core
+```
+feat(core): initialize the core module
+
+- Set up the core structure
+- Added initial configurations and settings
+- Created basic utility functions
+```
+
+### 2. Release with build and tag version
+```
+chore(release): build and tag version 1.0.0
+
+- Built the project for production
+- Created a new tag for version 1.0.0
+- Updated changelog with release notes
+```
+
+### 3. Adding a new feature
+```
+feat(auth): add user authentication
+
+- Implemented user login and registration
+- Added JWT token generation and validation
+- Created middleware for protected routes
+```
+
+### 4. Fixing a bug
+```
+fix(api): resolve issue with data fetching
+
+- Fixed bug causing incorrect data responses
+- Improved error handling in API calls
+- Added tests for the fixed bug
+```
+
+### 5. Update a doc (Sphinx)
+```
+docs(sphinx): update API documentation
+
+- Updated the Sphinx documentation for API changes
+- Added examples for new endpoints
+- Fixed typos and formatting issues
+```
+
+### 6. Update dependencies (packages)
+```
+chore(deps): update project dependencies
+
+- Updated all outdated npm packages
+- Resolved compatibility issues with new package versions
+- Ran tests to ensure no breaking changes
+```
+
+### 7. Update version for build and publish
+```
+chore(version): update version to 2.1.0 for build and publish
+
+- Incremented version number to 2.1.0
+- Updated package.json with the new version
+- Prepared for publishing the new build
+```
+
+### 8. Adding unit tests
+```
+test(auth): add unit tests for authentication module
+
+- Created tests for login functionality
+- Added tests for registration validation
+- Ensured 100% coverage for auth module
+```
+
+### 9. Refactoring codebase
+```
+refactor(core): improve code structure and readability
+
+- Refactored core module to enhance readability
+- Extracted utility functions into separate files
+- Updated documentation to reflect code changes
+```
+
+### 10. Improving performance
+```
+perf(parser): enhance parsing speed
+
+- Optimized parsing algorithm for better performance
+- Reduced the time complexity of the parsing function
+- Added benchmarks to track performance improvements
+```
+
+These examples cover various types of commits such as feature additions, bug fixes, documentation updates, dependency updates, versioning, testing, refactoring, and performance improvements.

CONTRIBUTING.md

@@ -1,28 +1,140 @@
-# How to contribute to django-iranian-cities
+# Contributing to django-iranian-cities
 
-## Did you find a bug?
+Thank you for considering contributing to `django-iranian-cities`! We welcome contributions from the community to help make this project better.
 
-- Ensure the bug was not already reported by searching on GitHub under Issues
-- If you're unable to find an open issue addressing the problem, open a new one. Be sure to include a title and clear description, as much relevant information as possible, and a code sample or an executable test case demonstrating the expected behavior that is not occurring.
+## Table of Contents
 
-## Did you write a patch that fixes a bug?
+- [Contributing to django-iranian-cities](#contributing-to-django-iranian-cities)
+  - [Table of Contents](#table-of-contents)
+  - [Getting Started](#getting-started)
+  - [Running Tests](#running-tests)
+  - [Code Style](#code-style)
+  - [Pre-commit Hooks](#pre-commit-hooks)
+    - [Setting Up Pre-commit Hooks](#setting-up-pre-commit-hooks)
+  - [Submitting a Pull Request](#submitting-a-pull-request)
+  - [Reporting Issues](#reporting-issues)
+  - [Additional Resources](#additional-resources)
 
-- Open a new GitHub pull request with the patch.
-- Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
+## Getting Started
 
-## Did you fix whitespace, format code, or make a purely cosmetic patch?
+1. **Fork the repository on GitHub**:
 
-Changes that are cosmetic in nature and do not add anything substantial to the stability, functionality, or testability of [project name] will generally not be accepted (read more about our rationales behind this decision).
+   Go to the [django-iranian-cities](https://github.com/your-username/django-iranian-cities) repository and click on the "Fork" button in the top-right corner.
 
-## Do you intend to add a new feature or change an existing one?
+2. **Clone your fork locally**:
 
-- Suggest your change in the <[email protected]> and start writing code.
-- Do not open an issue on GitHub until you have collected positive feedback about the change. GitHub issues are primarily intended for bug reports and fixes.
+   ```bash
+   git clone https://github.com/your-username/django-iranian-cities.git
+   cd django-iranian-cities
+   ```
 
-## Do you have questions about the source code?
+3. **Install dependencies using Poetry**:
 
-- Ask any question about how to use django-iranian-cities in the [sage team slack].
+   If you don't have Poetry installed, you can install it by following the instructions on the [Poetry website](https://python-poetry.org/docs/#installation).
 
-django-iranian-cities is a volunteer effort. We encourage you to pitch in and join the team!
+   ```bash
+   poetry install
+   ```
 
-S.A.G.E. Team
+4. **Create a new branch for your feature or bugfix**:
+
+   ```bash
+   git checkout -b feature/your-feature
+   ```
+
+## Running Tests
+First check out `Django_Iranian_Cities_Pytest_Guide.md` file for writing tests
+
+We use `pytest` for testing. To run the tests, execute:
+
+```bash
+poetry run pytest
+```
+
+Ensure that all tests pass before submitting a pull request.
+
+## Code Style
+
+We use `black` and `isort` to format our code. Please ensure your code is formatted correctly before submitting a pull request:
+
+```bash
+poetry run black .
+poetry run isort .
+```
+
+Additionally, we use `flake8` and `pylint` for linting. You can run these tools to check for code style issues:
+
+```bash
+poetry run flake8
+poetry run pylint django_iranian_cities
+```
+
+## Pre-commit Hooks
+
+We use `pre-commit` to ensure code quality and consistency. Pre-commit hooks will run automatically before each commit to check and format the code.
+
+### Setting Up Pre-commit Hooks
+
+1. **Install pre-commit**:
+
+   ```bash
+   poetry add --dev pre-commit
+   ```
+
+2. **Install the pre-commit hooks**:
+
+   ```bash
+   poetry run pre-commit install
+   ```
+
+3. **Run pre-commit hooks manually (optional but recommended before committing)**:
+
+   ```bash
+   poetry run pre-commit run --all-files
+   ```
+
+The pre-commit configuration is defined in the `.pre-commit-config.yaml` file. Make sure to review and understand the hooks configured.
+
+## Submitting a Pull Request
+
+1. **Commit your changes**:
+
+   Write clear and descriptive commit messages. Follow the guidelines in the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification if possible.
+
+   ```bash
+   git commit -am 'feat: add new email feature'
+   ```
+
+2. **Push to the branch**:
+
+   ```bash
+   git push origin feature/your-feature
+   ```
+
+3. **Open a pull request on GitHub**:
+
+   Go to the original repository on GitHub and open a pull request. Provide a clear and descriptive title and description for your pull request. Link to any relevant issues or discussions.
+
+4. **Wait for review**:
+
+   One of the project maintainers will review your pull request. Be responsive to feedback and be prepared to make changes if necessary.
+
+## Reporting Issues
+
+If you find a bug or have a feature request, please open an issue on GitHub. Provide as much detail as possible to help us understand and address the issue:
+
+1. **Go to the [Issues](https://github.com/your-username/django-iranian-cities/issues) section of the repository.**
+2. **Click on "New issue".**
+3. **Fill out the issue template with relevant details.**
+
+## Additional Resources
+
+- [Poetry Documentation](https://python-poetry.org/docs/)
+- [Black Documentation](https://black.readthedocs.io/en/stable/)
+- [isort Documentation](https://pycqa.github.io/isort/)
+- [pytest Documentation](https://docs.pytest.org/en/stable/)
+- [flake8 Documentation](https://flake8.pycqa.org/en/latest/)
+- [pylint Documentation](https://pylint.pycqa.org/en/latest/)
+- [Pre-commit Documentation](https://pre-commit.com/)
+
+Thank you for contributing!

CONTRIBUTORS.md

@@ -0,0 +1,16 @@
+# Contributors
+
+We would like to thank the following people for their contributions to the `django-iranian-cities` project:
+
+## Core Contributors
+
+- **Sepehr Akbarzadeh**
+  - GitHub: [Sepehr akbarzadeh](https://github.com/sepehr-akbarzadeh)
+  - Email: [email protected]
+  - Contributions: Project creator and lead maintainer.
+
+---
+
+To be added to this list, please contribute to the project by submitting a pull request, opening issues, or helping improve the documentation. We appreciate all contributions, big and small!
+
+If you have contributed and are not listed here, please feel free to add your name and details in a pull request.