New developer documentation

[jamoore]

This requirement has been added to take some of the less critical documentation stories from #6296 for more immediate release. As discussed in Paris with a number of new developers coming onboard, both in Dundee and at various other sites, it will be critical to be able to get them up to speed quickly and painlessly. The primary output of this requirement should be a very small number of landing pages which a new developer (core, satellite, open-source) can be pointed out to find all the necessary information for getting started. This includes various tasks like uploading public keys, etc, basic OME/RO background information, commit procedures and testing requirements, and then how to start learning the appropriate APIs.

See #6296

Content copied from #6948 "Working with code base"

Umbrella ticket for defining

• code style/policy.
• enforcing copyright.
• Define header of files.
• define how to work with github
• how to work with tools like Eclispe, Pycharm
• etc.

Build process (previously #6951)

• integration of insight build. see #3940
• training material
  • where to put it.
  • maintenance.
  • when to build
  • etc.
• Let devs only build they need e.g. B-F, insight

Branch merging (previously #6934)

• In order to have continuous integration of active branches before they are merged into develop, we will need to have jobs which take properly marked branches from all github forks, merge them into a single branch, and then test that branch.
• Moving to future for us to investigate when we again have multiple branches / PRs all simultaneously active. The hope would be that such a build would prevent us from having to manually push to merge-green / merge-blue. Any merge failures would be detected immediately.

See #2125. Those stories should likely be added here as tickets.

[hflynn]

Given the work that has gone into the developer docs already, should we now be downgrading the importance of this ticket and changing the milestone? Remaining things don't look to be a critical priority to me.

[jmoore]

Unfortunately, Helen, I don't think so. Fundamentally, the test of whether or not "new develop docs" is usable is whether or not new members to the team and external developers can find what they need and easily get up-to-speed. Perhaps someone else wants to chime in, but my feeling is there we're not there yet.

[hflynn]

Fair enough, I was probably being overly optimistic!

[spli]

I think we're still lacking a good introductory page of links. Documenting one-off things (e.g. setting up ssh keys) isn't actually that important because they'll be someone to hand-hold you when you start. The bigger issues are the things that crop up a few weeks after starting.... things like figuring out unit-tests, where to find things, what the different components are, the build system, etc. A lot of it is already somewhere in the docs, so maybe a FAQ style page with links to subsections within the relevant page would do.

[wmoore]

We have the page of links, they just need improving. ​https://www.openmicroscopy.org/site/support/omero4/developers/index.html

The general introduction page I wrote is too specific to my point of view (client-side Python dev) ​https://www.openmicroscopy.org/site/support/omero4/developers/GettingStarted.html

Then we basically need to go through the first page of every sub-section, just updating and re-writing. And eventually get around to doing ALL the pages.