|
1 | | -# Contribution guide |
| 1 | +# Contributing |
2 | 2 |
|
3 | | -Want to contribute? There are a few things you need to know. |
| 3 | +We love your input! The following is a set of guidelines for contributing to the **Prisma Decision API**. |
4 | 4 |
|
5 | | -TBD |
| 5 | +Whether it's reporting a bug, proposing new features, discussing the current state of the code, or submitting a fix — we want to make contributing as easy and transparent as possible. |
| 6 | + |
| 7 | +## Ground Rules |
| 8 | + |
| 9 | +1. We use [Black](https://github.com/psf/black) and [Flake8](https://flake8.pycqa.org/) for Python formatting/linting, and C# nullable reference types with implicit usings for .NET. |
| 10 | +2. All endpoints must be testable and covered by unit/integration tests. |
| 11 | +3. Pre-commit hooks must pass before pushing (see [Code Style](#code-style)). |
| 12 | +4. Security vulnerabilities must be reported privately — see [SECURITY.md](SECURITY.md). |
| 13 | + |
| 14 | +## Getting Started |
| 15 | + |
| 16 | +This repository contains two API services: |
| 17 | + |
| 18 | +- **PrismaDotnetApi/** — .NET 8 (C#) with ASP.NET Core and Entity Framework Core |
| 19 | +- **PrismaFastApi/** — Python 3.11+ with FastAPI |
| 20 | + |
| 21 | +### Prerequisites |
| 22 | + |
| 23 | +- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) |
| 24 | +- [Python 3.11+](https://www.python.org/downloads/) with [Poetry](https://python-poetry.org/) |
| 25 | +- [Docker & Docker Compose](https://docs.docker.com/get-docker/) (recommended) |
| 26 | +- [pre-commit](https://pre-commit.com/) |
| 27 | + |
| 28 | +### Local Development Setup |
| 29 | + |
| 30 | +Can be find [here](https://github.com/equinor/prisma-decision-api#quick-start) |
| 31 | + |
| 32 | +## Commits |
| 33 | + |
| 34 | +We strive to keep a consistent and clean git history. All contributions should adhere to the following: |
| 35 | + |
| 36 | +1. All tests should pass on all commits |
| 37 | +2. A commit should do one atomic change on the repository |
| 38 | +3. The commit message should be descriptive |
| 39 | + |
| 40 | +We follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/): |
| 41 | + |
| 42 | +- **fix:** patches a bug (correlates with PATCH in Semantic Versioning) |
| 43 | +- **feat:** introduces a new feature (correlates with MINOR in Semantic Versioning) |
| 44 | +- **BREAKING CHANGE:** introduces a breaking API change (correlates with MAJOR in Semantic Versioning) |
| 45 | +- Other types are allowed: `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:` |
| 46 | + |
| 47 | +### Commit Message Format |
| 48 | + |
| 49 | +1. Separate subject from body with a blank line |
| 50 | +2. Limit the subject line to 50 characters |
| 51 | +3. Capitalize the subject line |
| 52 | +4. Do not end the subject line with a period |
| 53 | +5. Use the imperative mood in the subject line |
| 54 | +6. Wrap the body at 72 characters |
| 55 | +7. Use the body to explain *what* and *why* vs. *how* |
| 56 | + |
| 57 | +Reference: [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) |
| 58 | + |
| 59 | +## Pull Request Process |
| 60 | + |
| 61 | +1. Work on your own fork of the main repo. |
| 62 | +2. Squash/organize your work into meaningful atomic commits. |
| 63 | +3. Push your commits and make a **draft** pull request. Describe what the pull request is about and link the relevant issue. |
| 64 | +4. Ensure that all CI checks pass (both .NET and Python test workflows). |
| 65 | +5. While you wait, carefully review the diff yourself. |
| 66 | +6. When all tests have passed and you are happy with your changes, change your pull request to **"Ready for review"** and request a code review. |
| 67 | +7. As a courtesy to the reviewer(s), you may mark commits that react to review comments with `fixup` (see `git commit --fixup`) rather than immediately squashing and force pushing. |
| 68 | +8. When the review is concluded, squash what needs squashing and merge. |
| 69 | + |
| 70 | +### Pull Request Scoping |
| 71 | + |
| 72 | +Ideally a pull request will be small in scope and atomic, addressing precisely one issue. It is permissible to fix minor details (formatting, linting, simple refactoring) in the vicinity of your work. |
| 73 | + |
| 74 | +If you want to make changes that are not directly related to the issue you're working on, create a separate PR to avoid noise in the review process. |
| 75 | + |
| 76 | +## Reporting Bugs |
| 77 | + |
| 78 | +Create a new issue to report a bug, including: |
| 79 | + |
| 80 | +- A quick summary and/or background |
| 81 | +- Steps to reproduce — be specific and give sample code if you can |
| 82 | +- What you expected would happen |
| 83 | +- What actually happens |
| 84 | +- Any relevant logs or error messages |
| 85 | + |
| 86 | +## Proposing Features |
| 87 | + |
| 88 | +Create a new issue to propose new features, including: |
| 89 | + |
| 90 | +- Brief description of the feature |
| 91 | +- What problem/issue it will solve |
| 92 | +- Acceptance criteria — how should it look when finished |
| 93 | + |
| 94 | +## Versioning & Releases |
| 95 | + |
| 96 | +This project uses [Semantic Versioning](https://semver.org/). Version tags (`v*`) trigger automated deployment workflows: |
| 97 | + |
| 98 | +1. Pushing a `v*` tag runs migrations against the test environment |
| 99 | +2. Production promotion is handled via the CI/CD pipeline |
| 100 | +3. Deployment tracking tags are created automatically (e.g., `prod-deploy-v1.0.0`) |
| 101 | + |
| 102 | +## License |
| 103 | + |
| 104 | +By contributing, you agree that your contributions will be licensed under the [GNU General Public License](LICENSE). |
0 commit comments