Contributing to Exposed

Testing on Apple Silicon

To run Oracle XE tests, you need to install Colima container runtime. It will work in pair with your docker installation.

After installing, you need to start the colima daemon in arch x86_64 mode:

The test task can automatically use colima context when needed, and it's better to use default context for other tasks. To switch the context to default, run:

Make sure that default is used as default docker context:

Pull Requests

Contributions are made using Github pull requests:

1. Fork the Exposed repository, because imitation is the sincerest form of flattery.

2. Clone your fork to your local machine.

3. Create a new branch for your changes.

4. Create a new PR with a request to merge to the master branch.

5. Ensure that the description is clear and refers to an existing ticket/bug if applicable, prefixing the description with EXPOSED-, where refers to the YouTrack issue.

6. When contributing a new feature, provide motivation and use-cases describing why the feature not only provides value to Exposed, but also why it would make sense to be part of the Exposed framework itself.

7. If the contribution requires updates to documentation (be it updating existing contents or creating new one), please file a new ticket on YouTrack.

8. Make sure any code contributed is covered by tests and no existing tests are broken. We use Docker containers to run tests.

9. Execute the detekt task in Gradle to perform code style validation.

10. Finally, make sure to run the apiCheck Gradle task. If it's not successful, run the apiDump Gradle task. Further information can be found here.

Style Guides

A few things to remember:

• Your code should conform to the official Kotlin code style guide except that star imports should always be enabled. (ensure Preferences | Editor | Code Style | Kotlin, tab Imports, both Use import with '*' should be checked).

• Every new source file should have a copyright header.

• Every public API (including functions, classes, objects and so on) should be documented, every parameter, property, return types, and exceptions should be described properly.

Test functions:

• Begin each test function name with the word test.

• Employ camelCase for test function names, such as testInsertEmojisWithInvalidLength.

• Refrain from using names enclosed in backticks for test functions, because KDocs cannot reference function names that contain spaces.

• In the definition of test functions, use a block body instead of an assignment operator. For example, do write fun testMyTest() { withDb{} }, and avoid writing fun testMyTest() = withDb{}.

Commit messages

• Commit messages should be written in English.

• Their title should be prefixed according to Conventional Commits.

• They should be written in present tense using imperative mood ("Fix" instead of "Fixes", "Improve" instead of "Improved"). See How to Write a Git Commit Message.

• When applicable, prefix the commit message with EXPOSED- where represents the YouTrack issue number.

• Add the related bug reference to a commit message (bug number after a hash character between round braces).