Provide documentation about Che development conventions

[garagatyi]

Description

Currently, we have some code that uses Feature toggle technique to add Workspace.Next flow support into the current version of workspace bootstrapping flow. In my recent PR I was told that our convention is to develop features in long-leaving feature branches. I couldn't find any development conventions in Che documentation, so decided to create this issue. There are some conventions that somewhat followed by contributors, but since they are not described anywhere it is hard for a contributor to follow them and for a maintainer to make sure they are followed.

[garagatyi]

@eivantsov @gazarenkov

[gazarenkov]

IMO it is not that much for documentation for the time but more about technical/architectural decisions, to make "good practices" and avoid "code uglification". It should be decoupled from application logic by design (that's exactly my point in the issue you mentioned).

[garagatyi]

If there are no docs in the project about conventions contributors would struggle to figure out how to make a contribution to the project that would be accepted by maintainers. Saying that something should be done in another manner should be supported by the documentation to provide an easier flow of contribution to the project. Especially it affects contributors that didn't spend years on the project and don't know all the implicit rules.

[gazarenkov]

@garagatyi sorry, I do not understand your point, is it about Feature Toggles or something else? Like what "something" should be done in what "another manner" :)

Feel free proposing wording you'd like to add to the project documentation.

[garagatyi]

I mean all the conventions project has, for example, feature branch/feature toggle, property/env vars naming, license headers, formatting, license compliance and everything else that maintainers use to analyze a contribution for any kind of standards compliance.

[garagatyi]

@dneary FYI

[gazarenkov]

@garagatyi well, I think most of the things you listed are somehow (no one said it is perfect though :) ) addressed in the project wiki (except probably mentioning feature branches practice).

Feel free proposing wording you'd like to add to the project documentation.

[garagatyi]

Indeed, https://github.com/eclipse/che/wiki contains some useful information. Thank you, I forgot about the wiki. It is kinda confusing having docs in 3 places:

• official docs https://www.eclipse.org/che/docs/
• wiki https://github.com/eclipse/che/wiki
• in the repo, such as here and here

But what about topic feature branch vs feature toggle, do you think I need to create a separate issue to discuss the topic there?

[gazarenkov]

yes, it would probably be a good idea to describe the problem to solve, initial direction and some practical references and discuss it. I just would not expect a "blitzkrieg", it sounds like a long way to go.

[garagatyi]

I created an issue for the discussion regarding feature toggle technique here.

Closing this issue since it seems other parts are present in the wiki. I'm welcoming other community members to comment or reopen the issue if you think that something related to the topic is still missing.