docs: Add developer documentation, AGENTS.md

.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 <!-- insert issue # or URL -->
+
+<!-- Change "Contributes to" to "Closes" if this PR, when merged, completely resolves the referenced issue. 
+Leave "Contributes to" if the changes need to be released first. -->
+
 _Please describe._
 
 ## How did you test this code?

.gitignore

@@ -23,3 +23,5 @@ src/CI_COMMIT_SHA
 .DS_Store
 .idea
 *.iml
+
+AGENTS.local.md

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

CLAUDE.md

@@ -0,0 +1 @@
+Read @AGENTS.md

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.

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

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.

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`.

docs/Makefile

@@ -22,4 +22,4 @@ build:
 
 .PHONY: serve
 serve:
-	npm run serve
+	npm run start

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 <YOUR_DOC> --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.

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
+<Contributing />
 
-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.

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"
+
+<ApiDeveloperGuide />
+<FrontendDeveloperGuide />
+<DocsDeveloperGuide />

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.

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