Development Guide

[bart2]

I think a development guide might be useful for new people thinking about contributing to the project. Knowing about the older JDK requirement would save me quite some time when I first tried to set up Android Studio to be able to build xDrip.

Also, see a recent question related to this subject: #2926

[Navid200]

Placing documentation/guides inside the repository is not a good idea.
Documentation needs to be kept up-to-date or it will harm more than help.
The nature of the repository is that the PRs take a long time to be reviewed. Including documentation in the repository increases the subjects the lead developer will have to spend time on.
I have open PRs that I prefer him to look at than to PRs about documentation.

I show you an example: https://github.com/NightscoutFoundation/xDrip/blob/master/Documentation/WatchGuide.md
Do you really think that is up-to-date?

In my opinion, documentation should be separate and there should be links in the wiki pointing to the approved guides/documentation.
I am more than happy to arrange all of that if I had permission to edit the wiki.

Why I don't have a section in my guide about development is that we have never had a discussion about how exactly (actively) we should train developers. It is a two-edged sword.

[bart2]

@Navid200, I think that makes sense. I don't mind documentation being in a wiki, as long as it is accessible somewhere (and we could link to it from https://github.com/NightscoutFoundation/xDrip/blob/master/CONTRIBUTING.md) :)

@jamorham, would it be possible to setup wiki permissions for @Navid200? I'd be happy to contribute to it as well.

[Navid200]

@bart2 Just to clarify.

1- In my opinion, it helps if documentation is outside the repository to minimize the time jamorham has to spend on it so that he can spend the limited time he has on the technical front, where we really need him.

2- This would take control completely out of his hands though as far as which documentation he considers acceptable.
The solution to that is that the Wiki as well as the README.md, which he has complete control on can have pointers to external documentation.
This allows him to let users know which external sites he approves of.
So, if an external documentation becomes outdated, all he has to do is to change the pointer in the wiki or Readme to point to a more up-to-date external documentation.
He can decide to point to multiple sites or a single site or whatever.

3- The wiki contains some minimal documentation. If he really likes to directly be in control of some particular document, he can put it in the wiki.

4- jamroham already has documentation outside the repository in github.io. He can also maintain some documentation there and point to it from the wiki again if he likes to be in direct control of some material literally.

All of this gives the repository owner effectively full control on documentation promoted by this repository.

This is my opinion and I am happy to be corrected.

The Readme.md needs a PR and I can open such if this is acceptable.
However, I am not aware of a reasonable way to open a PR to modify the wiki.

[jamorham]

Any development guide should probably include which versions of Android studio have been tested to be okay as there are often introduced breaking changes/regressions with later versions that could trip people up. Likewise the lombok plugin is required and not mentioned here.

[bart2]

@jamorham, yeah including Android Studio version(s) in the development guide is a good idea.

I was not aware of the lombok plugin. I was able to build and test xDrip+ without it. I think it further highlights a need for an official development guide.

Where would you see it hosted though? Does wiki seem a reasonable place for it? Or should we keep it in the code repo itself (for example this PR)?

[jamorham]

I was thinking of bundling the lombok plugin in the source tree as since google broke it it needs to be loaded separately but I am not sure whether the one from the jetbrains repository has now been updated to work. It was previously integrated as a standard part of IDEA.