diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index a351e0a7970e..f3add4a0e987 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,12 +1,17 @@ Thanks for submitting a PR! Please check the boxes below: -- [ ] I have added information to `docs/` if required so people know about the feature! -- [ ] I have filled in the "Changes" section below? -- [ ] I have filled in the "How did you test this code" section below? -- [ ] I have used a [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) title for this Pull Request +- [ ] I have read the [Contributing Guide](/CONTRIBUTING.md). +- [ ] I have added information to `docs/` if required so people know about the feature. +- [ ] I have filled in the "Changes" section below. +- [ ] I have filled in the "How did you test this code" section below. ## Changes +Contributes to + + + _Please describe._ ## How did you test this code? diff --git a/.gitignore b/.gitignore index c639e95f4aa8..51a06d5a8f1b 100644 --- a/.gitignore +++ b/.gitignore @@ -23,3 +23,5 @@ src/CI_COMMIT_SHA .DS_Store .idea *.iml + +AGENTS.local.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000000..c259ff4e1f6a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,10 @@ +Prioritise @AGENTS.local.md, if present. + +Use British English. + +# Tasks + +Install Git hooks: `make install-hooks` +For backend code, read @api/README.md +For frontend code, read @frontend/README.md +For docs.flagsmith.com source, read @docs/README.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000000..23562a5fe3bc --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +Read @AGENTS.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7ce3362efb24..929bf59025b1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,21 +1,34 @@ -# Contributing +# Contributing Guide -We're always looking to improve this project, open source contribution is encouraged so long as they adhere to these -guidelines. +We're always looking to improve this project, and we welcome your participation! Flagsmith accepts contributions via GitHub pull requests (PRs). This guide is intended to help ensure the success of your contribution. -## Pull Requests +## Create an issue -The Flagsmith team will be monitoring for pull requests. When we get one, a member of team will test the work against -our internal uses and sign off on the changes. From here, we'll either merge the pull request or provide feedback -suggesting the next steps. +Before opening a PR, we encourage you to [create an issue](https://github.com/Flagsmith/flagsmith/issues/new/choose) describing your problem or feature request. -### A couple things to keep in mind +We don't leave PRs unattended, but it will be easier for us to prioritise a review of your PR when there is a relevant issue at hand. -- If you've changed APIs, update the documentation. -- Keep the code style (indents, wrapping) consistent. -- If your PR involves a lot of commits, squash them using `git rebase -i` as this makes it easier for us to review. -- Keep lines under 80 characters. +You can submit a PR directly for problems such as spelling mistakes or other things where it's clear what the problem is. -### Windows support +If you decide to create an issue, be sure to search for an existing one first. -Flagsmith development under Windows is not currently supported. If you are contributing from Windows, consider using Windows Subsystem for Linux. +## Find an issue + +If you are prepared to contribute but are uncertain as to how, consider narrowing your search with issue filters. For instance: +- [is:issue state:open type:Bug no:assignee](https://github.com/Flagsmith/flagsmith/issues?q=is%3Aissue%20state%3Aopen%20type%3ABug%20no%3Aassignee) includes all current bugs. +- [is:issue state:open label:"good first issue" no:assignee](https://github.com/Flagsmith/flagsmith/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22%20no%3Aassignee) lists issues we think are good for newcomers. + +## Submit a PR + +1. The target branch should always be set to `main`, unless otherwise asked in the respective issue. +1. Feel free to open a draft pull request. If you open a regular PR, a reviewer will be assigned immediately and your PR will be considered ready for review, unless you specify otherwise in a PR comment. You're welcome to use a PR to run checks against unfinished code. +1. Once you have addressed the review feedback, preferably in new commits, reply to review comments, ensure the checks are passing and re-request a review. It is okay to not address the nitpicks and notes. +1. An approved PR is eventually merged into `main`. Documentation changes will get deployed immediately afterwards. Your frontend changes will get deployed to SaaS, and you can expect both backend and frontend changes to be included in the next release. + +## Setup local development + +The development tooling is intended for use with Linux or macOS, and [GNU Make](https://www.gnu.org/software/make/). Consider using Windows Subsystem for Linux (WSL) to develop on Windows. + +To install Git hooks, run `make install-hooks`. + +Each component provides its own Makefile in its respective subdirectory, and documents its usage and dependencies in a `README.md` file. diff --git a/Makefile b/Makefile index 46afa92d68ec..c21f8c838e7c 100644 --- a/Makefile +++ b/Makefile @@ -1,9 +1,19 @@ +.PHONY: install-pre-commit +install-pre-commit: + curl -LsSf uvx.sh/pre-commit/install.sh | sh + +.PHONY: install-hooks +install-hooks: install-pre-commit + pre-commit install + .PHONY: install install: - cd api && $(MAKE) install - cd docs && $(MAKE) install + $(MAKE) -C api install + $(MAKE) -C docs install + $(MAKE) -C frontend install .PHONY: lint lint: - cd api && $(MAKE) lint - cd docs && $(MAKE) lint + $(MAKE) -C api lint + $(MAKE) -C docs lint + $(MAKE) -C frontend lint diff --git a/README.md b/README.md index 26345a543ea2..3c5a70545964 100644 --- a/README.md +++ b/README.md @@ -52,24 +52,18 @@ Please go to the following page and choose a password: http://localhost:8000/pas ## Flagsmith Open Source -The Flagsmith repository is comprised of two core components - the [REST API](https://github.com/Flagsmith/flagsmith/tree/main/api) and the [frontend dashboard](https://github.com/Flagsmith/flagsmith/tree/main/frontend). - -Further documentation for these can be found at: - -* [API](https://docs.flagsmith.com/deployment/hosting/locally-api) -* [Frontend](https://docs.flagsmith.com/deployment/hosting/locally-frontend) +We love contributions from the community and are always looking to improve! Here are our [contribution guidelines](https://docs.flagsmith.com/platform/contributing). ## Flagsmith hosted SaaS + You can try our hosted version for free at https://flagsmith.com -## Community Resources + Contribution Guidelines +## Community Resources * [Visit our docs](https://docs.flagsmith.com/) * [Chat with other developers on Discord](https://discord.com/invite/hFhxNtXzgm) * If you need help getting up and running, please [get in touch](https://www.flagsmith.com/contact-us) -We love contributions from the community and are always looking to improve! Here are our [contribution guidelines](https://docs.flagsmith.com/platform/contributing). - ## Open Source Philosophy The majority of our platform is open source under the [BSD-3-Clause license](https://github.com/Flagsmith/flagsmith?tab=BSD-3-Clause-1-ov-file#readme). A small number of repositories are under the MIT license. diff --git a/api/README.md b/api/README.md new file mode 100644 index 000000000000..58ed3928addc --- /dev/null +++ b/api/README.md @@ -0,0 +1,81 @@ +## Flagsmith API + +### Local development + +The project assumes the following tools installed: +- [Python](https://www.python.org/downloads/). Any version allowed by `requires-python` in `pyproject.toml` is supported. +- [GNU Make](https://www.gnu.org/software/make/). +- Docker or a compatible tool like [Podman](https://podman.io/). We recommend [OrbStack](https://orbstack.dev/) for macOS. + +To install dev dependencies, run `make install`. + +To run linters, run `make lint`. + +To run tests, run `make docker-up test`. + +To prepare a dev database, run `make docker-up django-migrate`. + +To bring up a dev server, run `make serve`, or `make serve-with-task-processor` to run the Task processor alongside the server. + +### Code guidelines: testing + +The required diff test coverage for our backend PRs is 100%. This policy gives us more confidence to ship, helps us to find bugs earlier, and promotes the test-driven development (TDD) approach. We encourage you to add new tests, and modify existing ones, ahead of writing the code. + +This codebase includes two kinds of tests: +- Black box API tests in `tests/integration` directory. Ideally, these are intended to only invoke API endpoints, and verify their output. +- Tests for individual modules, classes and functions in `tests/unit` directory. + +We avoid class-based tests. To manage test lifecycle and dependencies, we rely on Pytest features such as fixtures, markers, parametrisation, and hooks. Read `conftest.py` for commonly used fixtures. + +We recommend naming test functions using the `test_{subject}__{condition}__{expected outcome}` template, e.g. `test_get_version__valid_file_contents__returns_version_number`. + +We use the Given When Then structure in all our tests. + +### Code guidelines: migrations + +To auto-generate migrations for your new code, run `make docker-up django-make-migrations`. + +The prompt will ask you for a name and not generate one; we avoid auto-generated migration names. + +Squash newly added migrations whenever you can. + +### Code guidelines: typing + +This codebase, including tests, is fully type-checked by Mypy in strict mode. Resolving existing `# type: ignore` comments is always welcome. If you happen to bring a new `# type: ignore` comment, please document the reason, and consider fixing a small number of adjacent `# type: ignore` comments, if possible and appropriate for the scope of your task. + +To run a full type check, run `make typecheck`. + +### Code guidelines: design and architecture + +Core API consists of Django apps with usual Django submodules like: +- `apps.py` +- `middleware.py` +- `models.py` +- `serializers.py` +- `views.py` +- `urls.py` + +We tend to add our own layers in the following modules: +- `constants.py` for app-wide constant variables. +- `dataclasses.py` for dataclass definitions, typically used for internal data transfer objects (DTOs). +- `mappers.py` for data mapping logic unrelated to API requests and responses. +- `services.py` for encapsulated business logic. Our goal with this layer is to make the views, models and serialisers leaner, so that the business logic is more clearly defined and easier to compose. +- `tasks.py` for defining asynchronous and recurring tasks. +- `types.py` for custom type definitions, including typed dicts. + +### Code guidelines: Flagsmith on Flagsmith + +To gate and gradually rollout features in the backend, we use the Flagsmith SDK in local evaluation mode: + +```python +from integrations.flagsmith.client import get_client + +flagsmith_client = get_client("local", local_eval=True) +flags = flagsmith_client.get_identity_flags( + organisation.flagsmith_identifier, + traits=organisation.flagsmith_on_flagsmith_api_traits, +) +ai_enabled = flags.is_feature_enabled("ai") +``` + +To modify or add flags, edit [integrations/flagsmith/data/environment.json](integrations/flagsmith/data/environment.json), or run `poetry run python manage.py updateflagsmithenvironment`. diff --git a/api/readme.md b/api/readme.md deleted file mode 100644 index b63cfb9519da..000000000000 --- a/api/readme.md +++ /dev/null @@ -1,4 +0,0 @@ -# We've moved - -API deployment and development instructions have -[moved to our Docs site](https://docs.flagsmith.com/deployment/locally-api) diff --git a/docs/Makefile b/docs/Makefile index ffda86dd9305..8ef3e87e6e82 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -22,4 +22,4 @@ build: .PHONY: serve serve: - npm run serve + npm run start diff --git a/docs/README.md b/docs/README.md index cc236cac1ce2..5c1ee8e84c9c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,14 +1,14 @@ -# Website +## Documentation -This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. +docs.flagsmith.com is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. -## Installation +### Installation ```console npm install ``` -## Local Development +### Local Development ```console npm run start @@ -38,7 +38,7 @@ If you want to apply any fixes discovered, you can run the following command: npx prettier --write ``` -## OpenAPI generator +### OpenAPI generator We are using the https://github.com/PaloAltoNetworks/docusaurus-openapi-docs plugin to generate the OpenAPI docs. If `static/api-static/edge-api.yaml` changes you will need to rebuild the static files with: @@ -50,7 +50,7 @@ npm run docusaurus gen-api-docs all and then commit them. -## Build +### Build ```console npm run build @@ -59,6 +59,6 @@ npm run build This command generates static content into the `build` directory and can be served using any static contents hosting service. -## Deployment +### Deployment This site is set to auto deploy to Vercel. diff --git a/docs/docs/project-and-community/contributing.md b/docs/docs/project-and-community/contributing.md index 39bed9a895e5..c774e37e66f5 100644 --- a/docs/docs/project-and-community/contributing.md +++ b/docs/docs/project-and-community/contributing.md @@ -1,64 +1,11 @@ --- title: Contributing Guide sidebar_position: 2 +hide_title: true --- -We're always looking to improve this project! Open source contribution is encouraged so long as they adhere to these guidelines. +import Contributing from "../../../CONTRIBUTING.md" -## Pull Requests + -The Flagsmith team will be monitoring for pull requests. When we get one, a member of team will test the work against our internal uses and sign off on the changes. From here, we'll either merge the pull request or provide feedback suggesting the next steps. - -### A couple things to keep in mind - -- If you've changed APIs, update the documentation. -- Keep the code style (indents, wrapping) consistent. -- If your PR involves a lot of commits, squash them using `git rebase -i` as this makes it easier for us to review. -- Keep lines under 80 characters. - -### Conventional Commits - -Please prefix the title of your PRs with one of the following [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/#summary) labels. E.g. `feat: My great feature`: - -- **feat**: A new feature or improvement to an existing feature -- **fix**: A bug fix -- **infra**: For Infrastructure-as-code type work -- **ci**: Changes to our CI/CD or build setup -- **docs**: Documentation only changes -- **deps**: Updating library dependencies -- **perf**: A code change that improves performance -- **refactor**: A code change that neither fixes a bug nor adds a feature -- **test**: Adding missing tests or correcting existing tests -- **chore**: Changes that don’t really live anywhere else (_please try NOT to use this label if possible_) - -## Pre-commit - -The application uses pre-commit configuration ( `.pre-commit-config.yaml` ) to run `black`, `flake8` and `isort` formatting before commits. - -To install pre-commit: - -```bash -# From the repository root -make install -pre-commit install -``` - -You can also manually run all the checks across the entire codebase with: - -```bash -pre-commit run --all-files -``` - -## Running Tests - -The application uses pytest for writing (appropriate use of fixtures) and running tests. Before running tests please make sure that `DJANGO_SETTINGS_MODULE` env var is pointing to the right module, e.g. `app.settings.test`. - -To run tests: - -```bash -DJANGO_SETTINGS_MODULE=app.settings.test pytest -``` - -## Adding Dependencies - -We use [Poetry](https://python-poetry.org/) for dependency management - please follow [their docs on adding dependencies](https://python-poetry.org/docs/basic-usage/#specifying-dependencies). +For detailed documentation, see the next section. diff --git a/docs/docs/project-and-community/development.md b/docs/docs/project-and-community/development.md new file mode 100644 index 000000000000..5d7a15510a21 --- /dev/null +++ b/docs/docs/project-and-community/development.md @@ -0,0 +1,12 @@ +--- +title: Developer Guides +sidebar_position: 3 +--- + +import ApiDeveloperGuide from "../../../api/README.md" +import FrontendDeveloperGuide from "../../../frontend/README.md" +import DocsDeveloperGuide from "../../../docs/README.md" + + + + diff --git a/docs/docs/project-and-community/release-notes.md b/docs/docs/project-and-community/release-notes.md index a2868832dc88..697f20553277 100644 --- a/docs/docs/project-and-community/release-notes.md +++ b/docs/docs/project-and-community/release-notes.md @@ -1,6 +1,6 @@ --- title: Release Notes -sidebar_position: 3 +sidebar_position: 4 --- We follow the [SemVer](https://semver.org/) version naming strategy. diff --git a/frontend/README.md b/frontend/README.md index ce8540ff2482..8d23cbd8c842 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,4 +1,3 @@ -# We've moved +## Flagsmith Frontend -Front end deployment and development instructions have -[moved to our Docs site](https://docs.flagsmith.com/deployment/locally-frontend) +TODO