Add documentation about template based project creation

[javiplx]

The readme from #48 cannot be merged on master, so I've preferred to use a different PR for this.

[elvanja]

OK, so if I got it right, this would be the flow, when automatic job creation is enabled:

• if direct match exists
  • use that job, just trigger the build for it
  • branch specifier must be exactly the same as payload branch, e.g. no wildcards
  • other modifiers apply too, e.g. "Inverse Of" must be off
• if matching project exists
  • copy it and set branch specifier to the branch from payload
  • this is much like regular matching but creates a new project if it founds a match
• if matching template group exists
  • from configured groups, find one who's key matches the project from payload
  • use it to create a new job, matching the payload exactly
• if all else fails
  • use the default template for creating a new job

So, if this is it, I am a bit confused. In https://github.com/elvanja/jenkins-gitlab-hook-plugin/pull/48/files#diff-3d205b5283c294e342010bb770b88b2fR21 you have declared 3 template types: templates, group templates and last resort template. The templates and group templates seem oddly similar. Can you share more details on what is the difference between them?

Also, on what would you base template key matching? Something like contains from payload's repository name?

Shouldn't we just then have a single map of templates? I think it covers all cases nicely. Even the default template could be set there as well, if we leave out the key. But, for the sake of clarity, it can be set separately as well.

[javiplx]

If I understand right, there are two basic questions

• why two template hashes (group and standard)
• merge processing of build_now for unknown branches and standard templates

About merging, although I've slightly modified the traditional processing or build_now, the template processing is fully detached because I want templates to be used only if the payload is for a fully unknown repository (that's the purpose of matching_uri method). If, for example, I have that repository on a disabled jenkins project, I don't want to re-create it from a template. On the other side, it is better not to use a template for a new branch because the jenkins project could have some additional tuning respect to the template should be used.

Respect to the two hashes, it might be not clearly explained, but they cover two very different cases. The standard is there for partial matches (_startwith?) against the repository name (the last path portion). And the group ones are for exact matches on gitlab groups (so named on web interface, but internally referred as namespace on gitlab code). They could be eventually get meld just by doing exact and partial matches both on repository name and group, but I see very little overlap. If you are using the public gitlab.com, your only interest will probably be the standard, and if you run your own gitlab instance you might be able to use only the group one, but it is unlikely that you use isolated enough groups.For example, in our case the "frontend" group holds php and java libraries and containers, each one with its own template, and even the mobile group has two flavors (android & ios), because the groups are created based on the developers working on them.

[elvanja]

Hey, I tried wrapping my head around this but without success :-) The problem is that I don't really use Gitlab anymore (Stash has replaced it) and some of the references you made are totally missing the target. Sorry.

If I may suggest, maybe it would be best if we can write down all the cases. For me to get the idea, and for us to have a written break down of features that are expected/needed. I'd be more than inclined to work on this with you, but I will need help. Especially since I don't use Gitlab daily, I'll need samples of usage and details on what behavior is expected.

For example, one flow we might describe is the "build job from 'frontend' group". For his, I'd need to know how this is set up on Gitlab, the payload is sent to Jenkins on commit, how would we like to treat such payload. Then I can create such an example and help with implementation. Don't know how to describe this better, but I feel you have a lot on your mind and I am just missing all that knowledge / experience to be productive in this matter.

I'd really like to just merge your code, but as you can see it is not easy since it is not based on current master and the method signatures really deffer. And I can't merge manually since I can't figure out what is the desired behavior. A Catch 22 situation :-)

Anyway, let me know if this feels OK to you. If so, we can maybe organize a call and see where it takes us.

[javiplx]

I think I've found a point which might clear your confusion. I don't know how gitlab worked when you started to work in this plugin, but the point is that the sample payload on spec/fixtures (as well as the one currently shown on gitlab documentation) is wrong respect to current push event payload. The wrong point is that the group / namespace is not there, maybe because it wasn't developed at that time. Both url and homepage should have it, and when current payload says

"url": "git@example.com:diaspora.git",
"homepage": "http://example.com/diaspora",

it should actually say

"url": "git@example.com:diaspora-dev/diaspora.git",
"homepage": "http://example.com/diaspora-dev/diaspora",

where diaspora-dev is the group. The groups behave in a very similar manner to github organizations, and when you enable personal repositories on gitlab (as well as in github), they are fully equivalent. As an example, if you go to current gitlab repository, it is at https://gitlab.com/gitlab-org/gitlab-ce, where gitlab-org is the group and gitlab-ce the repository name.

I've reported this issue to gitlab, and will soon prepare a merge request to fix this issue for rspec.

[javiplx]

merged at my fork