Improve this page

Policies Permalink to " Policies"

The JHipster development team follows some coding policies. You can see them as “best practices” or “guidelines”. They are enforced on the project itself, not on the generated code: if you use JHipster to generate your project, you absolutely do not have to follow them!

Those policies are followed by the development team, and you should follow them if you submit a Pull Request.

Policy 0: Policies are voted by the development team Permalink to "Policy 0: Policies are voted by the development team"

Each policy can be discussed or modified by the development team on the mailing list. Any significant change must be voted (+1 if you agree, -1 if you disagree).

Policy 1: Technologies used by JHipster have their default configuration and best practices used as much as possible Permalink to "Policy 1: Technologies used by JHipster have their default configuration and best practices used as much as possible"

For example, we use JPA, Spring, Angular and React the “usual way”, without some heavy configuration options and with their usual naming and coding conventions. We do this as:

  • Each technology usually has a very good reason to have those defaults
  • It’s much easier to understand how JHipster works if we don’t re-configure everything

We might only change a default configuration if it produces some issue with the other technologies used by JHipster. For example, to have Spring Security and Angular working together, we had to change Spring Security’s default configuration or if the default configuration makes our EJS templates extremely complex

Policy 2: Only add options/features when there is sufficient added-value in the generated code Permalink to "Policy 2: Only add options/features when there is sufficient added-value in the generated code"

JHipster has many options when generating a project. We only add those options when they are complex and imply configuring or coding several components.

Adding an option only because it saves a couple of lines to code isn’t a good usage of JHipster:

  • It’s easier to code those lines manually than to learn a new JHipster option
  • It will only make our generator more complex without adding any value

Policy 3: Use strict versions for third-party libraries on server side and client side Permalink to "Policy 3: Use strict versions for third-party libraries on server side and client side"

Only exception is dependencies on our libraries where relative versions work better. We’ve had many issues with library versions making conflicts. This is mostly a JavaScript issue, so to be clear: we use fixed libraries versions in package.json files that are generated.

Policy 4: We provide similar user/developer experience across different options provided for the same purpose as much as possible Permalink to "Policy 4: We provide similar user/developer experience across different options provided for the same purpose as much as possible"

An important aspect of JHipster is our user and developer experience and the ease with which you can swap one technology to another (ex: Client framework, Authentication, Database, etc) and hence it would be easier for developers if they are configured/coded as similar as possible. We can make exceptions when it violates other policies.

Policy 5: Developer experience can take precedence over policy 1, 2, 3 & 4. Permalink to "Policy 5: Developer experience can take precedence over policy 1, 2, 3 & 4."

This means that we need to make sure developer experience is not affected by below as much as possible

  • Feature additions
  • Hype driven development
  • Contributor convenience
  • Technology enthusiasm

Developer experience is subjective hence the below can be a rough guide for the JHipster community. It will be the overall experience of using JHipster as a product and a platform. That includes

  • The JHipster CLI experience (ease of use, intuitiveness, speed etc)
  • Generated code (quality, simplicity, readability, maintenance ease, upgradability, familiarity etc)
  • UX of Tools like JHipster online, JDL studio
  • Docs (Website & generated Readme)

When there is a disagreement on enforcement of this policy, there can be a case to case debate and vote on the mailing list to resolve it.