diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..d9a7d645 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,16 @@ + + +**What this PR does / why we need it**: + +**Which issue(s) this PR fixes**: + +Fixes # diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a555ffc0..2bc60b2b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,12 @@ -# Contributing to XP +# Development Guide: Contributing to XP -Thank you for your interest in contributing to XP. This document provides -some suggestions and guidelines on how you can get involved. +Thank you for your interest in contributing to XP. This document provides some suggestions and guidelines on how you can get involved. ## Become a contributor You can contribute to XP in several ways: -- Contribute to the XP codebase + +- Contribute to feature development for the XP codebase - Report bugs - Create articles and documentation for users and contributors - Help others answer questions about XP @@ -25,15 +25,137 @@ If you have an idea to improve XP, submit a feature request. It will be good to describe the use cases and how it will benefit XP users in your feature request. -### Make a pull request +## Making a pull request + +You can submit pull requests to fix bugs, add new features or improve our documentation. + +Here are some considerations you should keep in mind when making changes: + +- While making changes + - Make your changes in a [forked repo](#forking-the-repo) (instead of making a branch on the main XP repo) + - [Rebase from master](#incorporating-upstream-changes-from-master) instead of using `git pull` on your PR branch + - Install [pre-commit hooks](#pre-commit-hooks) to ensure all the default linters / formatters are run when you push. +- When making the PR + - Make a pull request from the forked repo you made + - Ensure you leave a release note for any user facing changes in the PR. There is a field automatically generated in the PR request. You can write `NONE` in that field if there are no user facing changes. + - Please run tests locally before submitting a PR: + - For Go, the [unit tests](#go-tests). + - For Python, the [e2e tests](#e2e-tests). + +### Forking the repo + +Fork the XP Github repo and clone your fork locally. Then make changes to a local branch to the fork. + +See [Creating a pull request from a fork](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) + +### Pre-commit Hooks + +Setup [`pre-commit`](https://pre-commit.com/) to automatically lint and format the codebase on commit: + +1. Ensure that you have Python (3.7 and above) with `pip`, installed. +2. Install `pre-commit` with `pip` & install pre-push hooks + + ```sh + pip install pre-commit + pre-commit install --hook-type pre-commit --hook-type pre-push + ``` + +3. On push, the pre-commit hook will run. This runs `make format` and `make lint`. + +## XP Management/Treatment Service using Go + +Both Management & Treatment services are written using Go, and the following describes how to setup your development environment. + +### Environment Setup + +- Install Golang, [`protoc` with the Golang & grpc plugins](https://developers.google.com/protocol-buffers/docs/gotutorial#compiling-your-protocol-buffers) + +#### API Specifications + +The OpenAPI specs for both services are captured in the `api/` folder. If these specs are updated, the developer is required to regenerate the API types and interfaces using the command `make generate-api`. + +#### Compiling Protos + +If there are proto changes required, you can recompile and generate them using `make compile-protos`. + +### Code Style & Linting + +We are using [golangci-lint](https://github.com/golangci/golangci-lint), and we can run the following commands for formatting. + +```sh +# Formatting code +make fmt + +# Checking for linting issues +make lint +``` + +### Go tests + +For **Unit** tests, we follow the convention of keeping it beside the main source file. + +For **Integration** tests, they are available for Treatment Service currently where we mock certain functionality of Management Service under `treatment-service/testhelper/mockmanagement` and utilize them in `treatment-service/integration-test`. + +1. Run Management Service tests via `make test-management-service`. +2. Run Treatment Service tests via `make test-treatment-service`. + +## XP E2E tests using Python + +### Environment Setup + +Setting up your development environment for E2E tests: + +1. Ensure that you have `make`, Python (3.7 and above) with `pip`, installed. +2. _Recommended:_ Create a virtual environment to isolate development dependencies to be installed + + ```sh + # Create & activate a virtual environment + python -m venv venv/ + source venv/bin/activate + ``` + +3. Install test dependencies + + ```sh + pip install -r tests/requirements.txt + ``` + +### Code Style & Linting + +XP E2E tests: + +- Conforms to [Black code style](https://black.readthedocs.io/en/stable/the_black_code_style.html) +- Has type annotations as enforced by `mypy` +- Has imports sorted by `isort` +- Is lintable by `flake8` + +To ensure your Python code conforms to XP Python code standards: + +- Autoformat your code to conform to the code style: + +```sh +make format-python +``` + +- Lint your Python code before submitting it for review: + +```sh +make lint-python +``` + +### E2E Tests + +This constitutes building Management Service and Treatment Service binaries and starting them for tests. + +1. Build Go services' binaries via `make build`. +2. Setup dependencies and run tests. + - Docker-compose setup -Submit a pull request to XP when you want to make changes to XP -codebase. You can submit pull requests to fix bugs, add new features or -improve our documentation. + ```sh + # Starts Postgres, PubSub Emulator and runs tests + make e2e + ``` -The process is normally as follows: -1. Fork this XP repository -2. Create a new branch in your forked repository -3. Commit the changes to the codebase -4. Make sure all the tests pass -5. Submit a pull request to the main XP codebase from your forked repository + - Individual services setup + - Start Postgres, Pubsub Emulator. + - Run `cd tests/e2e; python -m pytest -s -v` diff --git a/README.md b/README.md index dba27153..d47a47b1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # xp -[![License](https://img.shields.io/badge/License-Apache%202.0-blue)](https://github.com/feast-dev/feast/blob/master/LICENSE) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue)](https://github.com/gojek/xp/blob/master/LICENSE) ## Overview @@ -54,26 +54,8 @@ To test authorization for Management Service locally, make the following changes - Set AuthorizationConfig.Enabled=true in the config file that's being used - Issue requests to the app with the header User-Email: test-user@gojek.com -### API Specifications +## Contributing -The OpenAPI specs for both services are captured in the `api/` folder. If these specs are updated, the developer is required to regenerate the API types and interfaces using the command `make generate-api`. +XP is still under active development. Please have a look at our contributing and development guides if you want to contribute to the project: -### Tests - -For **Unit** tests, we follow the convention of keeping it beside the main source file. - -For **Integration** tests, they are available for Treatment Service currently where we mock certain functionality of Management Service under `treatment-service/testhelper/mockmanagement` and utilize them in `treatment-service/integration-test`. - -**End-to-End** tests can be found in tests/e2e, where we build Management Service and Treatment Service binaries to be used in Pytest. - -### Code style guidelines - -We are using [golangci-lint](https://github.com/golangci/golangci-lint), and we can run the following commands for formatting. - -```bash -# Formatting code -make fmt - -# Checking for linting issues -make lint -``` +- [Contribution Process for XP](https://github.com/gojek/xp/blob/main/CONTRIBUTING.md)