|
| 1 | +# Development Guidelines |
| 2 | + |
| 3 | +## General Development Guidelines |
| 4 | + |
| 5 | +* Auto-format code with `ddev test -fs`. |
| 6 | + |
| 7 | +## Python Type Hinting |
| 8 | + |
| 9 | +### Generating new code |
| 10 | + |
| 11 | +When generating python code, always add type hinting to the methods. Use modern syntaxis, for example, instead of using `Optional[str]` use `str | None` and instead of using `List[str]` use `list[str]`. |
| 12 | + |
| 13 | +If a method yields a value but we are not returning anything or we do not accept anything sent to the generator, it is better to type the method as Iterator to explicitely expose the API of the method as simply something the caller can iterate over. |
| 14 | + |
| 15 | +### Refactoring code |
| 16 | + |
| 17 | +When refactoring existing code, never add type hints to method that are not type hinted unless asked explicitely. |
| 18 | + |
| 19 | +### The case of AnyStr |
| 20 | + |
| 21 | +AnyStr is normally used to define the type of a variable that can be either a string or bytes. This is soon to be deprecated and, instead, type parameter lits are a better solution. If AnyStr is used as type of several arguments in a given method signature, it is better to use type parameter lists and define the function as a generic function. |
| 22 | + |
| 23 | +```python |
| 24 | +# Soon to be deprecated |
| 25 | +def func(a: AnySTr, b: AnyStr): |
| 26 | + pass |
| 27 | + |
| 28 | +# Preferred |
| 29 | +def func[T: (str, bytes)](a: T, b: T): |
| 30 | + pass |
| 31 | +``` |
| 32 | + |
| 33 | +This way, whether a and b are either strings or bytes, they cannot be mixed. |
| 34 | + |
| 35 | +If a single argument is present in the function, `str | bytes` is preferred. |
| 36 | + |
| 37 | +## Configuration Models |
| 38 | + |
| 39 | +**Applicable to:** `**/config_models/*.py`, `*/assets/configuration/spec.yaml` |
| 40 | + |
| 41 | +Don't modify files in `**/config_models/*.py` directly. To change those files edit assets/configuration/spec.yaml and then run the following commands: |
| 42 | + |
| 43 | +```shell |
| 44 | +ddev -x validate config -s <INTEGRATION_NAME> |
| 45 | +ddev -x validate models -s <INTEGRATION_NAME> |
| 46 | +``` |
| 47 | + |
| 48 | +## Testing |
| 49 | + |
| 50 | +Run unit and integration tests with `ddev --no-interactive test <INTEGRATION>`. For example, for the pgbouncer integration, run `ddev --no-interactive test pgbouncer`. |
| 51 | + |
| 52 | +Run E2E tests with `ddev --no-interactive env test <INTEGRATION> --dev`. For example, for the pgbouncer integration, run `ddev --no-interactive env test pgbouncer --dev`. |
| 53 | + |
| 54 | +Run specific tests with `ddev --no-interactive test <INTEGRATION> -- -k <PYTEST_FILTER_STRING>`, for example `ddev --no-interactive test kuma -- -k test_code_class_injection -s`. |
| 55 | + |
| 56 | +## Code Formatting |
| 57 | + |
| 58 | +Format code with `ddev test -fs <INTEGRATION>`. For example, for the pgbouncer integration, run `ddev test -fs pgbouncer`. |
| 59 | + |
| 60 | +## Changelog Management |
| 61 | + |
| 62 | +Changelog entries are typically generated using the `ddev` command and are required for all Python changes in `datadog_checks` subdirectories. Changelog entries are not required for changes in tests or assets. |
| 63 | + |
| 64 | +Changelog files are named `<PR_NUMBER>.<TYPE>` and placed in the integration's `changelog.d/` directory. |
| 65 | + |
| 66 | +### Version Bumping Behavior |
| 67 | + |
| 68 | +* `fixed` - Bug fixes. Bumps the **patch** version (e.g., 1.0.0 → 1.0.1) |
| 69 | +* `added` - New features. Bumps the **minor** version (e.g., 1.0.0 → 1.1.0) |
| 70 | +* `changed` - Breaking changes or significant modifications. Bumps the **major** version (e.g., 1.0.0 → 2.0.0) |
| 71 | + |
| 72 | +### Command Format |
| 73 | + |
| 74 | +`ddev release changelog new <TYPE> <INTEGRATION> -m "<MESSAGE>"` |
| 75 | + |
| 76 | +### Examples |
| 77 | + |
| 78 | +```shell |
| 79 | +# New feature |
| 80 | +ddev release changelog new added kafka_consumer -m "Bump OpenSSL in confluent-kafka to 3.4.1 on Windows." |
| 81 | + |
| 82 | +# Bug fix |
| 83 | +ddev release changelog new fixed sqlserver -m "Fix a bug where ``tempdb`` is wrongly excluded from database files metrics due to all instances inherited from ``SqlserverDatabaseMetricsBase`` share the same reference of auto-discovered databases." |
| 84 | + |
| 85 | +# Breaking change |
| 86 | +ddev release changelog new changed postgres -m "Update configuration options for connection pooling." |
| 87 | +``` |
| 88 | + |
| 89 | +## Documentation |
| 90 | + |
| 91 | +### New files added |
| 92 | + |
| 93 | +When a new file is added make sure to make it available through the navigation configuration in the mkdocs file. If it is not clear where it should go, ask. |
| 94 | + |
| 95 | +### Style |
| 96 | + |
| 97 | +Maintain style consistent. The style should be technical and professional. |
| 98 | + |
| 99 | +Do not start lines/paragraphs with an inline code. |
0 commit comments