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.

README.md

@@ -203,7 +203,8 @@ For more information visit the links below:
 
 ## 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.
+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).
+While issues are visible publicly, either creating a new issue or commenting on an existing one does require logging in to YouTrack.
 
 ## Community
 
@@ -212,13 +213,15 @@ Do you have questions? Feel free to [request an invitation](https://surveys.jetb
 
 ## Pull requests
 
-We actively welcome your pull requests. However, linking your work to an existing issue is preferred.
+We actively welcome your pull requests. However, linking your work to an [existing issue](https://youtrack.jetbrains.com/issues/EXPOSED) 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.
+-   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.
+-   If you make the existing code better, please let us know by filling out the PR template description.
+-   Please choose a PR title that starts with a [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/#summary) specification,
+    followed by the issue code and description. e.g. `fix: EXPOSED-123 Fix a specific bug`.
 
 See the [contribution guidelines](https://jetbrains.github.io/Exposed/contributing.html) for more details.
 

documentation-website/Writerside/topics/Contributing.md

@@ -43,21 +43,29 @@ docker context list
 
 ### 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
+   Please complete as many sections of the PR template description as applicable.
+7. If the contribution requires updates to documentation (be it updating existing contents or creating new one), please 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, please 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,16 +93,16 @@ 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
 
 There are multiple ways in which you can contribute to Exposed docs:
 
 - 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.
+Ensure that these modifications are applied directly within the `documentation-website` directory only, **not** to files in the `docs` folder.
 
 ## Community Support
 
@@ -104,7 +112,7 @@ 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.
+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.
 
 Before submitting an issue or feature request, please search YouTrack's existing issues to avoid reporting duplicates.
 

exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/Alias.kt

@@ -107,11 +107,15 @@ class Alias<out T : Table>(val delegate: T, val alias: String) : Table() {
         .orEmpty()
 }
 
+/** Interface common to all [Expression]s with temporary SQL identifiers. */
 interface IExpressionAlias<T> {
+    /** The aliased expression. */
     val delegate: Expression<T>
 
+    /** The temporary SQL identifier string. */
     val alias: String
 
+    /** Appends the SQL representation of this aliased expression to the specified [queryBuilder]. */
     fun queryBuilder(queryBuilder: QueryBuilder) = queryBuilder {
         if (delegate is ComparisonOp && (currentDialectIfAvailable is SQLServerDialect || currentDialectIfAvailable is OracleDialect)) {
             +"(CASE WHEN "