Skip to content

Commit c3de126

Browse files
xteraoxterao
authored
Merge pull request #233 from domaframework/document/developer-document
Create Developer Document
2 parents d7a7ca5 + eecd843 commit c3de126

File tree

6 files changed

+285
-0
lines changed

6 files changed

+285
-0
lines changed

‎CODE_OF_CONDUCT.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to making participation in our project and
7+
our community a harassment-free experience for everyone, regardless of age, body
8+
size, disability, ethnicity, sex characteristics, gender identity and expression,
9+
level of experience, education, socio-economic status, nationality, personal
10+
appearance, race, religion, or sexual identity and orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
* Using welcoming and inclusive language
18+
* Being respectful of differing viewpoints and experiences
19+
* Gracefully accepting constructive criticism
20+
* Focusing on what is best for the community
21+
* Showing empathy towards other community members
22+
23+
Examples of unacceptable behavior by participants include:
24+
25+
* The use of sexualized language or imagery and unwelcome sexual attention or
26+
advances
27+
* Trolling, insulting/derogatory comments, and personal or political attacks
28+
* Public or private harassment
29+
* Publishing others' private information, such as a physical or electronic
30+
address, without explicit permission
31+
* Other conduct which could reasonably be considered inappropriate in a
32+
professional setting
33+
34+
## Our Responsibilities
35+
36+
Project maintainers are responsible for clarifying the standards of acceptable
37+
behavior and are expected to take appropriate and fair corrective action in
38+
response to any instances of unacceptable behavior.
39+
40+
Project maintainers have the right and responsibility to remove, edit, or
41+
reject comments, commits, code, wiki edits, issues, and other contributions
42+
that are not aligned to this Code of Conduct, or to ban temporarily or
43+
permanently any contributor for other behaviors that they deem inappropriate,
44+
threatening, offensive, or harmful.
45+
46+
## Scope
47+
48+
This Code of Conduct applies both within project spaces and in public spaces
49+
when an individual is representing the project or its community. Examples of
50+
representing a project or community include using an official project e-mail
51+
address, posting via an official social media account, or acting as an appointed
52+
representative at an online or offline event. Representation of a project may be
53+
further defined and clarified by project maintainers.
54+
55+
## Enforcement
56+
57+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
58+
reported by contacting the project team at [email protected]. All
59+
complaints will be reviewed and investigated and will result in a response that
60+
is deemed necessary and appropriate to the circumstances. The project team is
61+
obligated to maintain confidentiality with regard to the reporter of an incident.
62+
Further details of specific enforcement policies may be posted separately.
63+
64+
Project maintainers who do not follow or enforce the Code of Conduct in good
65+
faith may face temporary or permanent repercussions as determined by other
66+
members of the project's leadership.
67+
68+
## Attribution
69+
70+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71+
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
72+
73+
[homepage]: https://www.contributor-covenant.org
74+
75+
For answers to common questions about this code of conduct, see
76+
https://www.contributor-covenant.org/faq

‎CONTRIBUTING.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Contributing to Doma Tools for IntelliJ
2+
3+
Thank you for your interest in contributing to this project!
4+
5+
Please follow the guidelines below to set up your environment and submit contributions.
6+
7+
## License
8+
9+
All original contributions to Doma Tools are licensed under ASL - [Apache License, version 2.0](https://www.apache.org/licenses/LICENSE-2.0) or later.
10+
11+
## About This Project
12+
13+
This plugin project is based on the [IntelliJ Platform Plugin Template](https://github.com/JetBrains/intellij-platform-plugin-template).
14+
15+
For other basic project information and best practices, please refer to the template repository.
16+
17+
## Reporting Issues
18+
19+
Use the [GitHub Issues page](https://github.com/domaframework/doma-tools-for-intellij/issues) to report bugs or request features.
20+
Write the issue in English to share it with many people.
21+
22+
## Contact
23+
24+
Let's work together to make this project better!
25+
26+
If you have any questions or suggestions, feel free to open an issue or contact the maintainers via GitHub.
27+
28+
## Prerequisites
29+
30+
- Install **IntelliJ IDEA** (2024.3 or later)
31+
- We recommend using the latest stable version of IntelliJ IDEA.
32+
- Install **Git** and configure your GitHub access
33+
- Install **JDK 17**
34+
35+
## Recommended IntelliJ IDEA Plugins
36+
37+
We recommend installing the following plugins in IntelliJ IDEA to improve your development experience:
38+
39+
You can install these plugins from `File > Settings > Plugins` in IntelliJ IDEA.
40+
41+
- **[Plugin DevKit](https://plugins.jetbrains.com/plugin/22851-plugin-devkit)**
42+
- **[PsiViewer](https://plugins.jetbrains.com/plugin/227-psiviewer)**
43+
- **[Spotless Gradle](https://plugins.jetbrains.com/plugin/18321-spotless-gradle)**
44+
- **[Ktlint](https://plugins.jetbrains.com/plugin/15057-ktlint)**
45+
46+
## Setting Up the Development Environment
47+
48+
1. **Clone the Repository**
49+
50+
```sh
51+
git clone https://github.com/domaframework/doma-tools-for-intellij.git
52+
cd doma-tools-for-intellij
53+
```
54+
55+
2. **Open the Project in IntelliJ IDEA**
56+
- Select `Open` and choose the project root directory.
57+
- IntelliJ will automatically import the Gradle project.
58+
59+
3. **Generate Custom Language Java Files (Grammar-Kit)**
60+
- Before building the project, generate the lexer and parser Java files using Grammar-Kit tasks:
61+
```sh
62+
./gradlew generateLexer
63+
./gradlew generateParser
64+
```
65+
- If you make changes to `Sql.bnf` or `Sql.flex`, be sure to re-run the above tasks to regenerate the Java files.
66+
- If you encounter build errors related to generated sources, try deleting the generated `gen` directory and re-running the Grammar-Kit tasks.
67+
68+
4. **Build the Project**
69+
- Use the Gradle tool window or run:
70+
```sh
71+
./gradlew build
72+
```
73+
74+
5. **Run/Debug the Plugin**
75+
- Use the Gradle task `runIde` to launch a sandboxed IntelliJ instance:
76+
```sh
77+
./gradlew runIde
78+
```
79+
80+
## Testing and Doma Dependency Management
81+
82+
When running tests, the plugin creates a virtual project environment with the required Doma dependencies.
83+
84+
- The Doma jar files for each version used in tests are located in the [`src/test/lib`](src/test/lib) directory.
85+
- The dependencies for the virtual project are managed in the `setUp()` method of [`DomaSqlTest`](src/test/kotlin/org/domaframework/doma/intellij/DomaSqlTest.kt).
86+
87+
## Code Style
88+
89+
We use [spotless](https://github.com/diffplug/spotless) and [google-java-format](https://github.com/google/google-java-format) for code formatting and style checking.
90+
91+
- To check or apply formatting, run the following Gradle tasks:
92+
```sh
93+
./gradlew spotlessCheck # Check code format
94+
./gradlew spotlessApply # Apply code format
95+
```
96+
- Alternatively, formatting will also be applied automatically when you build the project:
97+
```sh
98+
./gradlew build
99+
```
100+
101+
Please ensure your code is formatted with Spotless before submitting a pull request.
102+
103+
### Code Inspection
104+
105+
For advanced code inspection and static analysis, consider using [Qodana](https://www.jetbrains.com/qodana/).
106+
107+
- Qodana is a static analysis tool by JetBrains that can automatically check code quality in CI pipelines.
108+
- This repository includes a [`qodana.yml`](qodana.yml) file as an example configuration for Qodana.
109+
- For more details, refer to the [Qodana official documentation](https://www.jetbrains.com/help/qodana/).
110+
111+
## Branch Naming Rules
112+
113+
When creating a working branch, please follow the naming rules below according to the type of change.
114+
115+
These branch paths are used to categorize pull requests by label when automatically creating release drafts.
116+
117+
The mapping between branch paths and label names is configured in [`release-drafter.yml`](.github/release-drafter.yml).
118+
119+
- Bug fixes: `fix/`
120+
- Documentation changes: `document/`
121+
- CI-related changes: `ci/`
122+
- Dependency updates: `dependencies/` (Note: Version upgrades for dependencies are handled automatically by Renovate)
123+
- New features: `feature/`
124+
- Refactoring: `chore/`
125+
126+
For example, a bug fix branch might be named `fix/typo-in-readme`, and a new feature branch might be `feature/add-user-authentication`.
127+
128+
## Submitting a Pull Request
129+
130+
1. Create your branch from `main`.
131+
2. Make your changes and ensure all tests pass:
132+
```sh
133+
./gradlew check
134+
```
135+
3. Submit a pull request with a clear description of your changes.
136+
4. After creating a pull request, please link any related issues to the PR.

‎RELEASE_OPERATIONS.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Release Operations for Doma Tools for IntelliJ
2+
3+
This document describes the steps required to perform a release.
4+
5+
## Overview
6+
7+
The release process for this project is automated and consists of several stages, all managed on GitHub:
8+
9+
1. **Automatic Changelog and Release Draft Updates**
10+
- Every time a pull request (PR) is merged into `main`, GitHub Actions automatically updates `CHANGELOG.md` and the release draft.
11+
- A working branch named `doc/changelog-update-x.x.x` is created for updating `CHANGELOG.md`, and a draft pull request titled `Changelog update - x.x.x` is opened.
12+
- This pull request is force-pushed and updated with each new PR merged into `main`, reflecting the latest changes and release version.
13+
14+
2. **Release Note Publication and Marketplace Upload**
15+
- When a release note is published on GitHub, the [GitHub Actions workflow `release`](.github/workflows/release.yml) is triggered.
16+
- This workflow automatically uploads the latest version to the JetBrains Marketplace.
17+
18+
For other instructions on the Marketplace, please refer to the [official documentation](https://plugins.jetbrains.com/docs/marketplace/publishing-and-listing-your-plugin.html)
19+
20+
## Files Updated for Version Changes
21+
22+
Every time a pull request (PR) is merged into `main`, the following files are updated automatically:
23+
24+
- [`PluginUtil.kt`](src/main/kotlin/org/domaframework/doma/intellij/common/util/PluginUtil.kt)
25+
- [`logback.xml`](src/main/resources/logback.xml)
26+
- [`logback-test.xml`](src/main/resources/logback-test.xml)
27+
- [`gradle.properties`](gradle.properties)
28+
29+
## Release Procedure
30+
31+
1. **Confirm all required PRs are merged into `main`.**
32+
2. **Check the contents of [CHANGELOG.md](CHANGELOG.md) and the GitHub release draft**
33+
- Ensure that all necessary PRs are listed in both the updated `CHANGELOG.md` (from the draft pull request `Changelog update - x.x.x`) and the GitHub release draft.
34+
- Note: Documentation update PRs are not included in `CHANGELOG.md`.
35+
3. **Mark the draft pull request `Changelog update - x.x.x` as "Ready for Review"**
36+
- If the build action passes, merge the pull request.
37+
![ReadyForReview.png](images/ReadyForReview.png)
38+
4. **Publish the release on GitHub**
39+
- Open the release draft at [GitHub Releases](https://github.com/domaframework/doma-tools-for-intellij/releases).
40+
- Check "Set as the latest release" and click "Publish Release".
41+
![PublishRelease.png](images/PublishRelease.png)
42+
5. **After the [release action](.github/workflows/release.yml) completes, confirm the latest version is available on the JetBrains Marketplace.**
43+
6. **After the release, a draft for the next pre-release version is automatically created, and a commit is made to the `main` branch to set the next pre-release version.**
44+
45+
## Manual Release Procedure (if GitHub Actions fails)
46+
47+
If there is a problem with GitHub Actions and the automatic release fails, follow the steps below to perform a manual release:
48+
49+
1. Pull the latest changes to ensure your local `main` branch is up to date.
50+
2. Confirm that the version in each file matches the intended release version.
51+
- Files to check:
52+
- `PluginUtil.kt`
53+
- `logback.xml`
54+
- `logback-test.xml`
55+
- `gradle.properties`
56+
3. Run the Gradle task `buildPlugin` to build the plugin. ``` ./gradlew buildPlugin```
57+
4. Upload the generated zip file`build/distributions` from the JetBrains Marketplace management screen.
58+
- generated zip file: `build/distributions/Doma Tools for IntelliJ-x.x.x.zip`
59+
60+
---

‎SECURITY.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Security Policy
2+
We take all security bugs very seriously.
3+
4+
## Supported Versions
5+
6+
The community fixes security bugs in the latest version.
7+
We generally commit fixes only to the latest released version.
8+
9+
## Reporting Vulnerabilities
10+
11+
Email to the below address:
12+
13+
- toshihiro.nakamura at gmail.com

‎images/PublishRelease.png‎

21.1 KB
Loading

‎images/ReadyForReview.png‎

22.3 KB
Loading

0 commit comments

Comments
 (0)