The backend application for polymarq
Welcome to the Django Project! This guide outlines the best practices and procedures for contributing code to our project. By following these guidelines, you can help maintain a healthy and efficient development process.
- Getting Started
- Branching Strategy
- Pull Requests (PRs)
- Coding Standards
- Code Contribution Workfows
- Testing
- Documentation
- Review Process
- Continuous Integration
- Merging
- Issue Tracking
- License
-
Fork the Repository: Start by forking the main project repository on GitHub or the version control system of your choice.
-
Clone Your Fork: Clone your forked repository to your local development environment:
git clone https://github.com/so-fast/polymarq_backend.git
-
Set Up Remote: Add the main project repository as a remote:
git remote add upstream https://github.com/so-fast/polymarq_backend.git
-
Install Dependencies: Install project dependencies and set up your development environment as specified in the project's documentation.
- Branch Names:
- Create feature branches with descriptive names (e.g.,
feature/add-authentication
). - Use hyphens as word separators in branch names.
- Avoid using special characters or spaces in branch names.
- Create feature branches with descriptive names (e.g.,
- Branch from Main: Create feature or bug-fix branches from the
develop
branch (or the project's default development branch).
- Descriptive Titles:
- Provide a clear and descriptive title for your PR.
- Description:
- Write a detailed description that explains the purpose of the PR, the problem it addresses, and the changes made.
- Include links to relevant issues.
- Reviewers:
- Assign one or more reviewers to your PR.
- Reviewers should be knowledgeable about the codebase and the area you're modifying.
- Labeling:
- Label your PR appropriately (e.g., bug, feature, documentation) to help with categorization.
- PEP 8: Follow the Python Enhancement Proposal 8 (PEP 8) coding style guide.
- Consistency: Maintain consistency with existing code. Adhere to the project's coding conventions.
- Docstrings: Include clear and informative docstrings for classes, functions, and modules.
- Comments: Add comments where necessary to explain complex logic or provide context.
- Imports: Organize imports according to PEP 8 guidelines. Use absolute imports for intra-project modules.
- Branch Strategy:
- Use a Git branching strategy like Gitflow or GitHub Flow to structure your branches. Gitflow is suitable for more complex projects with regular releases, while GitHub Flow is simpler and suits continuous deployment.
- Develop and Main Branches:
- Use
develop
as the integration branch where feature branches are merged for testing. - Use
main
as the stable branch for production releases.
- Use
- Feature Branches:
- Developers should create feature branches off
develop
for their tasks. - Name feature branches descriptively, including the issue or task number, e.g.,
feature/123-add-user-auth
.
- Developers should create feature branches off
- Commits and Pull Requests:
- Encourage small, focused commits with clear and concise commit messages.
- Each feature or bugfix should have its own pull request (PR).
- Ensure PR titles and descriptions are informative.
- Use GitHub Issues:
- Create a GitHub Issue for each task or bug.
- Include details, acceptance criteria, and labels (e.g., bug, enhancement, feature) to categorize and track issues.
- Link Issues to PRs:
- Link PRs to the corresponding GitHub Issue. Use keywords like "Closes #123" or "Fixes #456" in PR descriptions to auto-close issues when the PR is merged.
- Task Status:
- Use labels (e.g., "In Progress," "Review," "Done") to indicate the status of an issue or PR.
- Regularly update the status of issues and PRs.
- DoD Checklist:
- Ensure all checklist items are completed before marking a task as "Done."
- Acceptance Criteria:
- Verify that all acceptance criteria are met before closing an issue or merging a PR.
- Semantic Versioning:
- Follow Semantic Versioning (SemVer) to version your releases.
- Release Notes:
- Document release notes for each version, detailing changes, improvements, and bugfixes.
- Release Branches:
- Create a release branch from
develop
for final testing before merging tomain
.
- Create a release branch from
- Continuous Integration:
- Use CI/CD pipelines to automate testing and deployment for each release.
- Rollback Plan:
- Have a rollback plan in place in case of critical issues with a release.
- Tagging Releases:
- Tag releases in your version control system to easily reference historical releases.
- Unit Tests: Write unit tests for new features and ensure that existing tests remain functional.*
- Test Coverage: Aim for high test coverage. Cover edge cases and potential failure scenarios.*
- Continuous Integration: Ensure that your code passes CI/CD checks and tests on all supported platforms.* (More context on the asterisks below)
- ReadMe: Keep the project's ReadMe updated with relevant information, including installation instructions and usage examples.
- Inline Documentation: Document code using inline comments and docstrings.
- API Documentation: If your changes affect APIs, update the API documentation accordingly.
- Reviewers:
- Reviewers should provide constructive feedback and suggestions.
- Address comments and concerns promptly.
- Approval: PRs should receive at least one approval from a reviewer before merging.
- Testing: Ensure that the changes work as intended and do not introduce new issues.
- CI/CD Pipelines: Make sure your PR passes all CI/CD pipelines (e.g., linting, testing).
- Fix Failures: If CI/CD pipelines fail, address the issues and retest.
- Squash Commits: If your PR has multiple commits, consider squashing them into a single commit with a descriptive message.
- Rebase: Before merging, rebase your branch onto the latest
main
branch to ensure a clean history. - Fast Forward: Use "fast-forward" merges when possible to maintain a linear history.
- Link to Issues: Reference relevant issues in PRs and commit messages using keywords (e.g., "Closes #123").
- Keep Issues Updated: Update issue statuses, descriptions
Moved to settings.
-
To create a normal user account, just go to Sign Up and fill out the form. Once you submit it, you'll see a "Verify Your E-mail Address" page. Go to your console to see a simulated email verification message. Copy the link into your browser. Now the user's email should be verified and ready to go.
-
To create a superuser account, use this command:
$ python manage.py createsuperuser
For convenience, you can keep your normal user logged in on Chrome and your superuser logged in on Firefox (or similar), so that you can see how the site behaves for both kinds of users.
Running type checks with mypy:
$ mypy polymarq_backend
To run the tests, check your test coverage, and generate an HTML coverage report:
$ coverage run -m pytest
$ coverage html
$ open htmlcov/index.html
$ pytest
Moved to Live reloading and SASS compilation.
This app comes with Celery.
To run a celery worker:
cd polymarq_backend
celery -A config.celery_app worker -l info
Please note: For Celery's import magic to work, it is important where the celery commands are run. If you are in the same folder with manage.py, you should be right.
To run periodic tasks, you'll need to start the celery beat scheduler service. You can start it as a standalone process:
cd polymarq_backend
celery -A config.celery_app beat
or you can embed the beat service inside a worker with the -B
option (not recommended for production use):
cd polymarq_backend
celery -A config.celery_app worker -B -l info
In development, it is often nice to be able to see emails that are being sent from your application. For that reason local SMTP server MailHog with a web interface is available as docker container.
Container mailhog will start automatically when you will run all docker containers. Please check cookiecutter-django Docker documentation for more details how to start all containers.
With MailHog running, to view messages that are sent by your application, open your browser and go to http:https://127.0.0.1:8025