Policy updates

[Deepu K Sasidharan]

Hello team,

I hope all of you are aware of the policies we have in the team. Lately, I feel that we have been slipping a little bit when it comes to these policies and also I think some of the items need an overhaul. Also sometimes I feel like we are not taking user/developer experience into consideration which has been one of our driving goals in the past. So I'm proposing some changes to the policies here. Please vote +1 if you agree and -1 if you don't. If you don't agree please provide the reason for that. If you agree but want some minor changes feel free to propose that along with a +1

Please not that our users are developers so user experience = developer expereince

Blue: current policy

Green: new policy

Yellow: update

Red: removed

Proposed: 

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 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 templating extremely complex

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: for the Java code, follow the default Intellij IDEA coding style
There are many ways to format your code. We follow the default rules provided by Intellij IDEA.

[Removed as we use prettier now mostly and makes this insignificant]

Policy 3: use strict versions for third-party libraries on server side and client side. Only exception is 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: Developer experience must take precedence over policy 1, 2 & 3. This means that we need to make sure developer experience is not affected by

- Feature additions

- Hype driven development

- Contributor convenience

- Technology enthusiasm 

Policy 5: We provide similar user/developer experience across different options provided for the same purpose (ex: Client framework, Authentication etc) as much as possible. We can make exceptions when it violates policy 4

Thanks & Regards,

Deepu

[Pierre Besson]

Hi Deepu,

+1

I appreciate your effort to improve and update our policies. I like your policies 4 and 5 as I think they were previously unofficially agreed in discussions on the mailing list. 

I really like your policy 4 but it feels strange to state that this new policy supersedes 1,2 and 3. It makes it hard to reason about what this implies... Also I think we need to define "developer experience" even though this is hard to do. Let me give a personal definition: "Developer experience relates to the feelings of developers interacting with the codebase (navigating, running, deploying, ...), focusing strongly on ease of making and testing changes".

Best regards,

Pierre

--
You received this message because you are subscribed to the Google Groups "JHipster dev team" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jhipster-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jhipster-dev/CAFXry57PK3GtDZB4f7dG%3DxNwAXRWO404DrHXT0wOB2poA2b0CA%40mail.gmail.com.

[Deepu K Sasidharan]

Thanks for the feedback Pierre.

Developer experience for our community IMO 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, upgradeability, familiarity etc)

- UX of Tools like JHipster online, JDL studio

- Docs (website & generated)

Let me give an example for the precedence. Lets say we go by a framework guideline but based on our particular community we know that developer experience can be better with a minor change so we go for it. I understand that this can be worded better

To view this discussion on the web visit https://groups.google.com/d/msgid/jhipster-dev/CAE4q%3DMQr1urSxf7Aj6NxZa%2BhMdtcuKpOYfZx%3DT_om8oO5%2BmF1g%40mail.gmail.com.

[Pierre Besson]

Okay I understand, I guess by precedence you mean it can override the other policies.

[Kaido Hallik]

Hi!

I think that most important is to follow frameworks style guides and best practices. Developer must live with code we generate. If we generate code that doesn't follow framework style guide and best practices then we are offering bad developer experience in this framework.

If developer generates code in framework 1 then developer expects good experience in this particular framework. Developer doesn't understand us if we explain: sorry about inconvenience, but we can't offer best developer experience to you because we have parallel frameworks too and we try to use similar codebase in all those parallel frameworks.

This has currently happened in Angular side:
* we have turned off Angular CLI unit test generation
* if developer finds some useful Angular example from the web then instead easily integrating example, developer must first do extra work:
 - extract tests to test folder
 - change imports in tests to get them work
This is not a good developer experience.

According to reasoning above I disagree with Policy 5. Instead I propose to supplement Policy 1 with addition: "Our primary goal is to follow used frameworks official style guides and best practices.".

Kaido.

--

[Pascal GRIMAUD]

Hi,

Angular coding style guide, from my point of view, it's an opinionated proposal, with some hello world examples, to learn Angular.

Same for other frameworks style guides and best practices.

JHipster is different, because it tries to provide real projects, which can be deployed in real production, for real customers.

So, we can totally provide our own best practices.

Since Angular.js, we split code and test, in 2 separate folders.

As far as I remember, I don't see any complaints, just people who asked why we choose this structure.

I don't see any value in changing this: our users won't be able to easily update their JHipster projects.

Did some of you have feedback from real users about this choice ? I worked on more than 20 real JHipster projects, for different customers, which are all deployed in production and no complaints for these choices.

But to make people happy, I'm pretty sure it's not so difficult to have this option with a flag or question.

Use ANGULAR_DIR instead of CLIENT_TEST_SRC_DIR (and do some minor change to put spec/ in constants)

To resume: I'm totally fine with what you proposed, Deepu.

Pascal

To view this discussion on the web visit https://groups.google.com/d/msgid/jhipster-dev/emc2131850-d6ff-4775-82c2-693aba263bbf%40sille.

[Deepu K Sasidharan]

Hi Kaido,

I do understand your point of view, but let me try to explain why we didn't have a policy that states we will stick to each tech's style guide (Style guides and best practices are different. We do follow the latter as much as possible and we do have a policy that stays we will stick to a techs default config)

1. We use a lot of technologies together and provide a full-stack application. Style guides from different techs here might not be compatible and in that case, the overall experience might not be that great. 
2. We have been following our own style guide (though not explicitly stated anywhere) from the beginning and as pascal mentioned so far no one has complained about it.
3. We are a platform/framework and hence it's OK to be opinionated if that provides our users best practices and a better dev experience. It will be difficult for us to follow style guides from every different framework we use. So we cherry-pick what works for us and discard the rest. this has been the approach from the beginning and has worked well for us, otherwise, we wouldn't have grown this much.

Now I do disagree with one of your points about developer experience being tied to a style guide. From my experience, this is not the case and again our user base is quite different. Of course, there will be some people who do not like what we do but from my interactions with users in the past, majority of our users like what we do and the way we do it. Now we can't make everyone happy so we try to keep the majority happy (This will be junior to medior java developers with not a lot of front-end experience, and the specific issue with the test folder is easier for this target group to follow) 

Now I don't see why policy 5 would be in issue for example you specified, as I mentioned earlier if everyone agrees to the test folder change then we have to do it for all client frameworks as its the normal way in React and Vue as well. Policy 5 it does state that developer experience takes priority. I would ask you to kindly reconsider your vote as the test folder change has nothing to do with the policy IMO

Thanks & Regards,

Deepu

[William Marques]

Hi,

That's a +1 from me, Deepu.

Let's focus on Deepu's proposal and not mix subjects please, we are already having a discussion for Angular ;)

To view this discussion on the web visit https://groups.google.com/d/msgid/jhipster-dev/CAFXry55wNHCT3i_m-SRFF%3DskUEz%3DjYwvGegbQbsT72nRwXAR7w%40mail.gmail.com.

[Kaido Hallik]

Hi Deepu,

Thanks for your answer.
When I read your original post then I was coming from test folder thread and I had feeling that the aim of this Policy 5 is to set legal obstacle to following Angular best practices in tests location.
I had feeling that it's maybe possible to achieve tests location change agreement only in Angular side but impossible for all 3 frameworks.
Now some time has passed and I believe you want the best with this policy to the JHipster.
So I'm changing my vote to policy 5 from against to neutral.

Kaido.

[Sendil Kumar N]

According to me the developer experience in Point 4 is subjective. We have a wide user base and It is difficult to democratize it. Someone needs  JHipster in the form of a framework (hide everything and just work) others want JHipster in the form of their own application (don't hide anything and I want to see & customise them).

I would like policy 4 to have a solution or approach to solve the issue when a dispute arises and suggest a way forward. It can be as simple as Policy 0. But it is important to have that solution mentioned there. On the other hand, contributor convenience and developer experience should be given equal importance. With core members struggling to find time to contribute, We should be encouraging (for new contributors too) and do not want to put contributor convenience at the bottom of the list.

(I also feel Policy 4 & 5 should be like unwritten rules rather than a policy by itself.)

P.S. I am neither against or towards the new policies. I am neutral too.

Thanks

Sendil 

To view this discussion on the web visit https://groups.google.com/d/msgid/jhipster-dev/ema3cf80aa-2cd2-4562-a0f0-e06cc5e24052%40sille.

[Deepu K Sasidharan]

What solution would you suggest Sendil?

To me longevity and success of the project is more important than anything else. 

In the end OSS or not we are providing a product that is used by developers and our success depends on adoption and satisfaction of the user base. Contributor convenience is important but that shouldn't have more priority than end dev experience and should be within reasonable limits. Projects which went that direction always end up dead as without steady adoption OSS projects will slowly die. I love this community too much to see that happen. 

So far IMO we have been doing good and going in the right direction. The reason for putting the policy in words is to ensure we don't move away from original goals even if the people who built the project originally moves away the project survives long term.

[Zs.]

Hi,

 Probably adding a line or two about a guideline about what kind of features are accepted - recently I'm having long discussions about various features one wants to add to criterias/filtering, which for me looks a bit too much - trying to push the current filtering implementation to be a GraphQL alternative.

To view this discussion on the web visit https://groups.google.com/d/msgid/jhipster-dev/CAFXry57Wat6U4o8fcE4OQeUdhpK7TjmYrHUOhH9meFwKz4q4ZA%40mail.gmail.com.

[Daniel Franco]

+1 for me too for Deepu proposition

To view this discussion on the web visit https://groups.google.com/d/msgid/jhipster-dev/CAOO3hRAy-CYmDwb1WQviSxbedLYO_vN5N-aqf86LHiqejL7PBg%40mail.gmail.com.