From d82ca3351d72036816735f19abde578ada9f4451 Mon Sep 17 00:00:00 2001 From: bog-walk <82039410+bog-walk@users.noreply.github.com> Date: Wed, 18 Dec 2024 10:15:06 -0500 Subject: [PATCH] docs: EXPOSED-670 Adjust YouTrack issue visibility and PR guidelines (#2337) * docs: EXPOSED-670 Adjust YouTrack issue visibility and PR guidelines Issues used to not have public visibility and this was made note of in docs, instead of changing this. Issues can now be viewed without logging in and no documented links should result in a 404 error. PR guideline section was also updated to make clear that existing issues should be used and add extra missing details. * docs: EXPOSED-670 Adjust YouTrack issue visibility and PR guidelines - Minor edits - Replace 'filing issue' and 'pull request' section in README with fleshed out contribution section - Reorganize contribution topic order of sections - Use HTML entities for { and } characters --- README.md | 29 ++--- .../Writerside/topics/Contributing.md | 103 ++++++++++-------- 2 files changed, 67 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 256558bbd6..d1be04ab9d 100644 --- a/README.md +++ b/README.md @@ -198,29 +198,27 @@ For more information visit the links below: - [Migration Guide](https://jetbrains.github.io/Exposed/migration-guide.html) - [Breaking changes](https://jetbrains.github.io/Exposed/breaking-changes.html) and any migration details - [Slack Channel](https://kotlinlang.slack.com/messages/exposed/) +- [Filing Issues](#contributing) - [Issue Tracker](https://youtrack.jetbrains.com/issues/EXPOSED)

-## Filing issues - -Please note that we are moving away from GitHub Issues for reporting of bugs and features. Please log any new requests on [YouTrack](https://youtrack.jetbrains.com/issues/EXPOSED). You must be logged in to view and log issues, otherwise you will be met with a 404. - ## Community Do you have questions? Feel free to [request an invitation](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up) for the [kotlinlang slack](https://kotlinlang.slack.com/) and join the project conversation at our [#exposed](https://kotlinlang.slack.com/messages/exposed/) channel. -

-## Pull requests +## Contributing + +We encourage your feedback in any form, such as feature requests, bug reports, documentation updates, and questions. +Note that we are moving away from GitHub Issues for this reporting. Log any new requests on [YouTrack](https://youtrack.jetbrains.com/issues/EXPOSED). +While issues are visible publicly, either creating a new issue or commenting on an existing one does require logging in to YouTrack. + +We also actively welcome your pull requests. However, linking your work to an [existing issue](https://youtrack.jetbrains.com/issues/EXPOSED) is preferred. -We actively welcome your pull requests. However, linking your work to an existing issue is preferred. -- Fork the repo and create your branch from main. -- Name your branch something that is descriptive to the work you are doing. i.e. adds-new-thing. -- If you've added code that should be tested, add tests and ensure the test suite passes. -- Make sure you address any lint warnings. -- If you make the existing code better, please let us know in your PR description. +See the full [contribution guide](https://jetbrains.github.io/Exposed/contributing.html) for more details. -See the [contribution guidelines](https://jetbrains.github.io/Exposed/contributing.html) for more details. +By contributing to the Exposed project, you agree that your contributions will be licensed under [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). +

## Examples @@ -487,8 +485,3 @@ Generated SQL: SQL: SELECT Users.id, Users.name, Users.city, Users.age FROM Users WHERE Users.age >= 18 Adults: b, c ``` - -## Contributing -Please see the [contribution guide](https://jetbrains.github.io/Exposed/contributing.html) before contributing. - -By contributing to the Exposed project, you agree that your contributions will be licensed under [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/documentation-website/Writerside/topics/Contributing.md b/documentation-website/Writerside/topics/Contributing.md index a3a0480998..8a6a8d18bd 100644 --- a/documentation-website/Writerside/topics/Contributing.md +++ b/documentation-website/Writerside/topics/Contributing.md @@ -6,58 +6,60 @@ We're delighted that you're considering contributing to Exposed! There are multiple ways you can contribute: -* Code +* Issues and Feature Requests * Documentation +* Code * Community Support -* Issues and Feature Requests This project and the corresponding community is governed by the [JetBrains Open Source and Community Code of Conduct](https://confluence.jetbrains.com/display/ALL/JetBrains+Open+Source+and+Community+Code+of+Conduct). Independently of how you'd like to contribute, please make sure you read and comply with it. -## Setup +## Issues and Feature Requests -### Testing on Apple Silicon -To run Oracle XE tests, you need to install [Colima](https://github.com/abiosoft/colima) container runtime. It will work in pair with your docker installation. -```shell -brew install colima -``` +If you encounter a bug or have an idea for a new feature, please submit it to us through [YouTrack](https://youtrack.jetbrains.com/issues/EXPOSED), +our issue tracker. While issues are visible publicly, either creating a new issue or commenting on an existing one does require logging in to YouTrack. -After installing, you need to start the colima daemon in arch x86_64 mode: -```Bash -colima start --arch x86_64 --memory 4 --network-address -``` +Before submitting an issue or feature request, search YouTrack's [existing issues](https://youtrack.jetbrains.com/issues/EXPOSED) to avoid reporting duplicates. -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: -```shell -docker context use default -``` +When submitting an issue or feature request, provide as much detail as possible, including a clear and concise description of the problem or +desired functionality, steps to reproduce the issue, and any relevant code snippets or error messages. -Make sure that default is used as default docker context: -```shell -docker context list -``` +## Documentation + +There are multiple ways in which you can contribute to Exposed documentation: + +- Create an issue in [YouTrack](https://youtrack.jetbrains.com/issues/EXPOSED). +- Submit a [pull request](#pull-requests) containing your proposed changes. + Ensure that these modifications are applied directly within the `documentation-website` directory only, **not** to files in the `docs` folder. ## Code ### Pull Requests -Contributions are made using Github [pull requests](https://help.github.com/en/articles/about-pull-requests): +Contributions are made using GitHub [pull requests](https://help.github.com/en/articles/about-pull-requests): -1. Fork the Exposed repository, because imitation is the sincerest form of flattery. +1. Fork the [Exposed repository](https://github.com/JetBrains/Exposed), 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](https://github.com/JetBrains/Exposed/compare) 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-{NUM}, where {NUM} refers to the YouTrack issue. +4. [Create](https://github.com/JetBrains/Exposed/compare) a new PR with a request to merge to the **main** branch. +5. Ensure that the PR title is clear and refers to an [existing ticket/bug](https://youtrack.jetbrains.com/issues/EXPOSED) if applicable, + prefixing the title with both a [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/#summary) + and EXPOSED-{NUM}, where {NUM} refers to the YouTrack issue code. + For more details about the suggested format, see [commit messages](#commit-messages). 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 + Complete as many sections of the PR template description as applicable. +7. If the contribution requires updates to documentation (be it updating existing content or creating new content), either do so in the same PR or file a new ticket on [YouTrack](https://youtrack.jetbrains.com/issues/EXPOSED). -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 + Any new public API objects should be documented with a [KDoc](https://kotlinlang.org/docs/kotlin-doc.html) in the same PR. +8. If the contribution makes any breaking changes, ensure that this is properly denoted in 3 ways: + - In the PR (and commit) title using the appropriate [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/#commit-message-with--to-draw-attention-to-breaking-change) + - By ticking the relevant checkbox in the PR template description + - By adding relevant details to [Breaking Changes](http://jetbrains.github.io/Exposed/breaking-changes.html) +9. Make sure any code contributed is covered by tests and no existing tests are broken. We use Docker containers to run tests. +10. Execute the `detekt` task in Gradle to perform code style validation. +11. 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](https://github.com/Kotlin/binary-compatibility-validator). ### Style Guides @@ -85,30 +87,37 @@ Test functions: * Their title should be prefixed according to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary). * 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](https://chris.beams.io/posts/git-commit/). -* When applicable, prefix the commit message with EXPOSED-{NUM} where {NUM} represents the YouTrack issue number. -* Add the related bug reference to a commit message (bug number after a hash character between round braces). +* When applicable, prefix the commit message with EXPOSED-{NUM} where {NUM} refers to the + [YouTrack issue](https://youtrack.jetbrains.com/issues/EXPOSED) code. +* An example could be: `fix: EXPOSED-123 Fix a specific bug` -## Documentation +### Setup -There are multiple ways in which you can contribute to Exposed docs: +#### Testing on Apple Silicon +To run Oracle XE tests, you need to install [Colima](https://github.com/abiosoft/colima) container runtime. It will work in pair with your docker installation. +```shell +brew install colima +``` -- Create an issue in [YouTrack](https://youtrack.jetbrains.com/issues/EXPOSED). -- Submit a pull request containing your proposed changes. -Ensure that these modifications are applied directly within the `documentation-website` directory. +After installing, you need to start the colima daemon in arch x86_64 mode: +```Bash +colima start --arch x86_64 --memory 4 --network-address +``` + +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: +```shell +docker context use default +``` + +Make sure that default is used as default docker context: +```shell +docker context list +``` ## Community Support If you'd like to help others, please join our Exposed [channel](https://kotlinlang.slack.com/archives/C0CG7E0A1) on the Kotlin Slack workspace and help out. It's also a great way to learn! -## Issues and Feature Requests - -If you encounter a bug or have an idea for a new feature, please submit it to us through [YouTrack](https://youtrack.jetbrains.com/issues/EXPOSED), -our issue tracker. - -Before submitting an issue or feature request, please search YouTrack's existing issues to avoid reporting duplicates. - -When submitting an issue or feature request, please provide as much detail as possible, including a clear and concise description of the problem or -desired functionality, steps to reproduce the issue, and any relevant code snippets or error messages. - Thank you for your cooperation and for helping to improve Exposed.