Skip to content

Commit

Permalink
docs: EXPOSED-670 Adjust YouTrack issue visibility and PR guidelines (#…
Browse files Browse the repository at this point in the history 
…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
  • Loading branch information
@bog-walk
bog-walk authored Dec 18, 2024
1 parent 59a4660 commit d82ca33
Show file tree
Hide file tree
Showing 2 changed files with 67 additions and 65 deletions.
29 changes: 11 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
<br><br>

## 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.
<br><br>

## 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).
<br><br>

## Examples

Expand Down Expand Up @@ -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).
103 changes: 56 additions & 47 deletions documentation-website/Writerside/topics/Contributing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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-&lcub;NUM&rcub;, where &lcub;NUM&rcub; 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
Expand Down Expand Up @@ -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-&lcub;NUM&rcub; where &lcub;NUM&rcub; 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.

0 comments on commit d82ca33

Please sign in to comment.