diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7e8b93980398..bdd493abaef7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,10 +25,6 @@ If you find a bug in the source code or a mistake in the documentation, you can **Please see the Submission Guidelines below**. -## Bug bounties - -If you submitted a Pull Request that fixes a ticket with the "\$100" tag, then you are eligible for our bug bounty program! Go to our [bug bounties documentation](https://www.jhipster.tech/bug-bounties/) for more information, and claim your money. - ## Feature Requests You can request a new feature by submitting a ticket to our [GitHub issues](https://github.com/jhipster/generator-jhipster/issues). If you @@ -37,26 +33,6 @@ would like to implement a new feature then consider what kind of change it is: - **Major Changes** that you wish to contribute to the project should be discussed first. Please open a ticket which clearly states that it is a feature request in the title and explain clearly what you want to achieve in the description, and the JHipster team will discuss with you what should be done in that ticket. You can then start working on a Pull Request. In order to communicate major changes proposals and receive reviews from the core team, you can also submit an RFC. - **Small Changes** can be proposed without any discussion. Open up a ticket which clearly states that it is a feature request in the title. Explain your change in the description, and you can propose a Pull Request straight away. -## RFCs - -Sometimes, major feature requests are "complex" or "substantial". In this case, GitHub Issues might not be the best tool to present them because we will need a lot of going back and forth to reach a consensus. - -So we ask that these feature request be put through a formal design process and have their specifications described in an "RFC" (request for comments) that will be validated by the team through a Pull Request Review. - -The RFC process is intended to provide a consistent and controlled path for major features and directions of the project. - -To submit an RFC follow those steps: - -1. Discuss the RFC proposal with the core team through GitHub issues or other channels -2. Create the initial GitHub issue for the Feature Request if it doesn't already exist -3. Copy the `rfcs/0-jhipster-rfc-template.md` to `rfcs/${featureRequestIssueNumber}-my-feature-request-name.md` -4. Fill in the RFC, make sure to complete every required section -5. Submit the RFC as a Pull Request with the summary of the proposal in the PR description -6. Build consensus and integrate feedback from the reviewers -7. The Pull Request is either accepted (merged), rejected (closed) or postponed (given an "on hold" status) - -Note: The JHipster RFC process is inspired by [Rust RFCs](https://rust-lang.github.io/rfcs/). - ## Submission Guidelines ### [Submitting an Issue](https://opensource.guide/how-to-contribute/#opening-an-issue) @@ -88,13 +64,16 @@ You can run `jhipster info` in your project folder to get most of the above requ Issues opened without any of these info will be **closed** without any explanation. +## Development environment setup + +See our [Development Guide](DEVELOPMENT.md) for more information on how to configure the JHipster generator for contributing. + ### [Submitting a Pull Request](https://opensource.guide/how-to-contribute/#opening-a-pull-request) Before you submit your pull request consider the following guidelines: - Search [GitHub](https://github.com/jhipster/generator-jhipster/pulls?utf8=%E2%9C%93&q=is%3Apr) for an open or closed Pull Request that relates to your submission. -- If you want to modify the JHipster generator, read our [Development Guide](DEVELOPMENT.md) - Follow our [Coding Rules](#rules). - In GitHub, send a pull request to `jhipster/generator-jhipster:main`. - **Every CI tests must pass**. @@ -109,6 +88,8 @@ To ensure consistency throughout the source code, keep these rules in mind as yo - Most files formatting are checked by prettier and eslint. - EJS files use a two-space indentation for template logic and follow the generated file rules for the templating parts. +The jhipster generator structure and file naming conventions are documented in the [RFC 6](./rfcs/6-jhipster-rfc-jhipster-generator-file-structure.md). + Please ensure to run `npm run lint` and `npm test` on the project root before submitting a pull request. You can also run `npm run lint-fix` to fix some of the lint issues automatically. ## Git Commit Guidelines @@ -183,3 +164,27 @@ or joined the [JHipster team](https://www.jhipster.tech/team/). [issue-template]: https://github.com/jhipster/generator-jhipster/issues/new?template=BUG_REPORT.md [feature-template]: https://github.com/jhipster/generator-jhipster/issues/new?template=FEATURE_REQUEST.md + +## RFCs + +Sometimes, major feature requests are "complex" or "substantial". In this case, GitHub Issues might not be the best tool to present them because we will need a lot of going back and forth to reach a consensus. + +So we ask that these feature requests be put through a formal design process and have their specifications described in an "RFC" (request for comments) that will be validated by the team through a Pull Request Review. + +The RFC process is intended to provide a consistent and controlled path for major features and directions of the project. + +To submit an RFC follow those steps: + +1. Discuss the RFC proposal with the core team through GitHub issues or other channels +2. Create the initial GitHub issue for the Feature Request if it doesn't already exist +3. Copy the `rfcs/0-jhipster-rfc-template.md` to `rfcs/${featureRequestIssueNumber}-my-feature-request-name.md` +4. Fill in the RFC, make sure to complete every required section +5. Submit the RFC as a Pull Request with the summary of the proposal in the PR description +6. Build consensus and integrate feedback from the reviewers +7. The Pull Request is either accepted (merged), rejected (closed) or postponed (given an "on hold" status) + +Note: The JHipster RFC process is inspired by [Rust RFCs](https://rust-lang.github.io/rfcs/). + +## Bug bounties + +If you submitted a Pull Request that fixes a ticket with the "\$100" tag, then you are eligible for our bug bounty program! Go to our [bug bounties documentation](https://www.jhipster.tech/bug-bounties/) for more information, and claim your money. diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 49186d9bb55c..82920656249c 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -17,7 +17,7 @@ Go to the [generator-jhipster project](https://github.com/jhipster/generator-jhi ### Set `jhipster` command to use the cloned project Since v8 `generator-jhipster` is written in TypeScript. -To run it you need to compile to JavaScript or use a just-in-time compilation. +To run it you need to compile to JavaScript or use a just-in-time compilation. `npm run compile` will be your best friend here: see [package.json script section](./package.json) for the entire list of commands. #### Running jit executable @@ -41,6 +41,19 @@ In your cloned `generator-jhipster` project, run `npm ci` and then run `npm link For testing, you will want to generate an application, and there is a specific issue here: for each application, JHipster installs a local version of itself. This is made to enable several applications to each use a specific JHipster version (application A uses JHipster 3.1.0, and application B uses JHipster 3.2.0). +#### Generating new applications from the tests samples using node bin/jhipster.cjs + +To generate a new application, you can run the following command in your terminal: + +```shell +node bin/jhipster.cjs generate-sample ng-default --global +``` + +From the root of your cloned `generator-jhipster` project, this will generate a sample application in the current folder using the local version of JHipster. ng-default is the name of the sample application, you can replace it with any other sample name in the [code samples](./test-integration/samples) to generate a sample application. By default, the sample will be generated in the `../jhipster-samples` folder. +For workspaces, an additional `jhipster-samples.code-workspace` file will be generated in the same folder, which can be used to open the samples in a single VSCode workspace. Still, you'll need to delete the `jhipster-samples.code-workspace` file if you want to generate another workspace sample in the same folder. + +#### Generating a new application using npm link + To overcome this, you need to run `npm link generator-jhipster` on the generated project folder as well, so that the local version has a symbolic link to the development version of JHipster. Also add the option `--skip-jhipster-dependencies` to generate the application ignoring the JHipster dependencies (otherwise a released version will be installed each time npm install/ci is called). You can later on re-add the dependency with the command `jhipster --no-skip-jhipster-dependencies`. @@ -95,6 +108,17 @@ To start debugging JHipster with **VSCode**, open the generator code in your wor It is also possible to debug sub generators by selecting one of the other debug options (for example `jhipster entity`). Those debug configurations are specified in the `.vscode/launch.json` file. +#### Debugging with IntelliJ IDEA + +When you start intelliJ IDEA on the `generator-jhipster` project, you'll have access to a run configuration letting execute any `.spec.ts` file within any package. +If you want to test a specific generator, you can create a new Node.js run configuration with the following settings: + +``` +application-parameters="generate-sample ms-ng-oauth2-mongodb-caffeine --global" path-to-js-file="bin/jhipster.cjs" typescript-loader="bundled" working-dir="$PROJECT_DIR$" +``` + +ms-ng-oauth2-mongodb-caffeine is the name of the sample application, you can replace it with any other sample name in the [code samples](./test-integration/samples) to generate a sample application. By default, the sample will be generated in the `../jhipster-samples` folder. + ## Generator implementation ### important config objects @@ -153,6 +177,8 @@ npm run ci:e2e:prepare # Starts the application using docker npm run ci:e2e:run # Runs e2e tests ``` +List of commands being in the package.json scripts section of the generated sample. + ## DX using vscode `generator-jhipster` add a series of vscode configurations for a better developer experience. diff --git a/rfcs/6-jhipster-rfc-jhipster-generator-file-structure.md b/rfcs/6-jhipster-rfc-jhipster-generator-file-structure.md new file mode 100644 index 000000000000..eed2c995e816 --- /dev/null +++ b/rfcs/6-jhipster-rfc-jhipster-generator-file-structure.md @@ -0,0 +1,177 @@ +# JHipster-RFC-6: jhipster generator file structure + + + +- Feature Name:jhipster_generator_file_structure +- Start Date: 2025-07-26 +- Issue: [jhipster/generator-jhipster#30187](https://github.com/jhipster/generator-jhipster/issues/30187) + +## Summary + +[summary]: #summary + +The goal of this RFC is to describe the generator conventions and file structure for the JHipster generator that enhances modularity, maintainability, and ease of use. The new structure will allow for better organization of files and directories, making it easier for developers to navigate and contribute to the project. + +## Motivation + +[motivation]: #motivation + +Improving the file structure of the JHipster generator is essential for several reasons: + +- **Modularity**: A well-defined structure allows for better modularization of the generator, making it easier to add, remove, or update features without affecting the entire codebase. +- **Maintainability**: A clear and consistent file structure makes it easier for developers to understand the codebase, locate files, and make changes. This is especially important for new contributors who may find the current structure confusing. +- **Ease of Use**: A more intuitive file structure can improve the developer experience, making it easier to find and use the generator's features. This can lead to increased adoption and contribution from the community. +- **Scalability**: As the generator grows and evolves, a well-organized file structure will help manage complexity and ensure that the codebase remains manageable. +- **Consistency**: Establishing conventions for file organization will lead to a more consistent codebase, making it easier for developers to follow best practices and contribute effectively. +- **Extensibility**: A modular file structure will facilitate the addition of new features and technologies, allowing the generator to adapt to changing requirements and trends in the software development landscape. Also to support leverage and ease the maintainance of third party blueprint providers in the long term. + +## Guide-level explanation + +[guide-level-explanation]: #guide-level-explanation + +This RFC description will be split into multiple parts: + +1. **Blueprint/Generators convention Overview**: will explain the different kind of generators and their purpose. +2. **Package and file Structure**: will describe the proposed file structure for each kind of generator. +3. Inheritance and Composition: will explain how the inheritance and composition of generators will work. +4. Methods and Functions: will detail the methods and functions that should be implemented in each file type. + +### Blueprint/Generators convention Overview + +[blueprint-generators-convention-overview]: #blueprint-generators-convention-overview + +The JHipster generator will be organized into several types of generators, each serving a specific purpose. The main types of generators are: + +- **Base Generators**: These are the core generators that provide the basic functionality of the downstream JHipster generator in the inheritance chain. This includes: + + - Tasks and Priorities + + - Contexts and object injection in functions (application, entities, etc.) + + - Facade of useful methods and functions (writing, propmting, etc.) +- **Feature Generators**: These generators add specific features or functionalities of jhipster (cucumber, kubernetes, ...). They can be used to extend the capabilities of the base generator by extending its core functionality. +- **Bootstrap Generators**: These generators are used to bootstrap the Features generators by executing common tasks that are common to many of them. + +## Reference-level explanation + +[reference-level-explanation]: #reference-level-explanation + +### Generators inheritance and composition + +[generators-inheritance-and-composition]: #generators-inheritance-and-composition + +Here is the proposed inheritance and composition possibility for the JHipster generator depending on their kind + +![Inheritance and composition diagram](./assets/rfc6-generators-inheritance-and-composition.jpg 'Inheritance and composition diagram') + +### Package and file structure + +[package-and-file-structure]: #package-and-file-structure + +#### Base Generators + +[base-generators]: #base-generators + +The base generators will be organized into a specific package structure to ensure clarity and maintainability. The proposed structure is as follows: + +```generator-jhipster/ +├── generators/ +│ ├── base-/ +│ │ ├── tasks.d.ts // optional +│ │ ├── types-mutations.ts // optional +│ │ ├── api.d.ts // optional +│ │ ├── index.ts +│ │ ├── generator.ts +│ │ ├── internal/ // optional +│ │ │ ├── .ts +│ │ ├── support/ // optional +│ │ │ ├── .ts +``` + +This structure allows for a clear separation of concerns, with each base generator having its own directory containing its tasks, types, and internal support files. The `internal` directory is used for helper functions that are not intended to be used outside the base generator, while the `support` directory contains utility functions that can be reused across different base generators. + +**tasks.d.ts**: This file defines the tasks that the base generator will declare. It includes the task names, descriptions, and any parameters required for each task as well as their orders and injected parameters. + +**types-mutations.ts**: This file defines the types and the mutation (from empty to fully hydrated object) used by the base generator, including any interfaces or type aliases that are specific to the base generator (Workspace, Application, Entities, Source template metadata, etc.). **RULE**: Types shouldn't contain any fields that are not directly related to the generator's functionality. They should be used to define the structure of the data that the base generator will work with, such as the application configuration or entity definitions. They can extend types from an upstream generator, and should not contain any business logic or methods. + +**api.d.ts**: This file defines the public API of the base generator, including any methods or properties that should be accessible to other generators. It serves as a contract for the base generator's functionality. + +**index.ts**: This file serves as the entry point for the base generator, exporting the main functionality and any public methods or classes that should be accessible to other generators. Usually exposes the generator class, api, types and tasks. + +**generator.ts**: This file contains the main generator class that extends the JHipster base generator class. +It should contains: + +- Facade of support methods and functions that can be used by the downstream generator (`write() {return import {'./support/write.ts'}.writeFile}`). +- Loading of contextual objects (application, entities, etc.) and their injection in the priorities methods. + +##### PROs + +- Clear separation of concerns, making it easier to understand and maintain the codebase. +- Modular structure allows for easy addition or removal of features without affecting the entire codebase. +- Consistent naming conventions and file organization improve readability and developer experience. +- Allow sibling feature generators (not part of the inheritance chain) to access the base generator's support methods and functions. + +#### Feature Generators file structure + +[feature-generators-file-structure]: #feature-generators-file-structure + +Feature generators will be organized in a similar way to base generators, but with a focus on adding specific features or functionalities. The proposed structure is as follows: + +```generator-jhipster/ +├── generators/ +│ ├── / +│ │ ├── commands.d.ts // optional +│ │ ├── types-mutations.ts // optional +│ │ ├── index.ts +│ │ ├── generator.ts +│ │ ├── files.ts // optional +│ │ ├── internal/ // optional +│ │ │ ├── .ts +│ │ ├── support/ // optional +│ │ │ ├── .ts +│ │ ├── resources/ // optional +│ │ │ ├── . +│ │ ├── templates/ // optional +│ │ │ ├── .ts +``` + +This structure allows for a clear organization of feature-specific files, with each feature generator having its own directory containing its cli commands, types, and internal support files. The `resources` directory is used for any static resources required by the feature generator, such as templates or configuration files. + +**commands.d.ts**: This file defines the CLI commands that the feature generator will provide. It includes the command names, descriptions, configuration storage, and any parameters required for each command. + +**files.ts**: This file contains the file templates and their associated metadata that the feature generator will use to generate files in the target application. It includes the file names, templates, and any parameters required for each file. **RULE**: the list of file to generate should have contextual information (application, entities, etc.) injected in the file data and never use the generator as a context. + +**resources/**: This directory contains any static resources required by the feature generator, such as configuration files, images, or other assets. These resources can be used by the generator during the generation process. + +**templates/**: This directory contains any templates used by the feature generator to generate files in the target application. These templates can be used to create files with specific content or structure based on the feature being added. + +**generator.ts**: This file contains the main generator class that extends the JHipster base generator class. The difference with the base generator is that: + +- It additionally contains the phase methods that will be executed in the generation process (i.e. `preparing`, `writing`, `post-processing`). +- It does not need to load the contextual objects (application, entities, etc.) as they are already loaded by the base generator. +- It can use the upstream base and feature generator's support methods and functions directly (i.e. `this.write()`) without the need to call `support/anysupport`. This will ease the refactoring of the `support`and `mutation` files, methods and functions in the future because it will not be necessary to change the import paths in the downstream feature generators. + +##### PROs + +- Clear organization of feature-specific files, making it easier to understand and maintain the codebase. +- Modular structure allows for easy addition or removal of features without affecting the entire codebase. +- Consistent naming conventions and file organization improve readability and developer experience. +- Allows for better organization of CLI commands, file templates, and mutation files, making it easier to manage the generation process. +- Provides a clear separation between static resources and templates, making it easier to manage and update them independently. +- Allows sibling feature generators (not part of the inheritance chain) to access the base generator's support methods or to reuse part of the mutations without the need to extend. + +## Drawbacks + +[drawbacks]: #drawbacks + +It includes a lot of changes to the current file structure and conventions, which may require significant effort to implement and migrate existing generators. It will lead to some refactoring in blueprints extending the V8 core generator and willing to upgrade. Hopefully, the amount of reuse of core business logic by these contributions will be much higher, which will lower their maintenance cost (and potential bugs) in the long run. + +## Unresolved questions + +[unresolved-questions]: #unresolved-questions + +The fine grained implementation details of each file as not been discussed yet, such as: + +- The amount and granularity of methods in the mutate (by file, by component, etc.) and support files. + +- The other packages outside generators: cli, jdl, tests, etc. will not be changed by this RFC. They will remain as they are for now, but the new file structure will allow for easier integration of these packages in the future. diff --git a/rfcs/assets/rfc6-generators-inheritance-and-composition.jpg b/rfcs/assets/rfc6-generators-inheritance-and-composition.jpg new file mode 100644 index 000000000000..a5ef857a7556 Binary files /dev/null and b/rfcs/assets/rfc6-generators-inheritance-and-composition.jpg differ