Try to describe what happens when a build hook is present,
a .spec file is present in the repo and the user pushes.

== Scenario 1 ==
- User pushes
- Web hook will trigger event 'rg_wh_build_send'
- 'rg_wh_build_send' will trigger event 'rg_wh_build_send_one' for each enabled environments
- 'rg_wh_build_send_one' will
	- get the pkg_maps, repo and subrepo info
	- sets exec:prepare_pkgs
	- will call 'rg_pkg_prepare_for_rgfs' to add rgfs details
	- will call 'rg_pkg_prepare_for_dotrepo' to add info to create user repositories
	- will call 'rg_builder_add'
- Builer will send the job to a worker
- Worker will start the VM
- Inside VM, script rg.sh is started
        - Checkout correct branch
	- .spec file is searched and BuildRequires are installed
	- 'build.sh' starts [as user 'build']
		- Secrets are exported
		- The commands defined in the webhook are run
	- 'build_rpms.sh' starts [as user 'build']
		- 'rg_build_rpm' shell function is called for '/mnt/target'
		- for each job[rpm_repo_files] 'rg_build_dotrepo /mnt/target-dotrepo-<subrepo_id>' is called
	- 'build_rgfs.sh' starts [as user 'root']
	- 'build_repo.sh' starts [as user 'build2']
		- If no pkg mapping is defined, exit
		- gpg keys are stored in /mnt/build2
		- Search for .rpm packages in /mnt/rpmbuild
		- Imports gpg keys
		- If flag exec:prepare_pkgs is set:
			- .rpms are copied into /mnt/build2/rpms/<pkg_repo_id}/{debug,os,src}[/username]
			- A file A, containing the rpms, is created and rpms are signed
		- For each mapping
			- a rgfs is mounted
			- if '+pending' dir is found, we add the rpms to the file A
			- if file A is empty, continue with next mapping
			- If a rpm file is already in the repo, remove the name from file A
			- if the build is done as uid 0, sign the '+pending' rpms
			- copy the signed rpms to rgfs dir
			- if uid is not 0 and pkg_repo uid != job_uid, save the pkg_subrepo_id into /mnt/build2/pkg_subrepo_dirty
			- If uid is 0 or pkg_repo_uid == job_uid, call rg_rpm_createrepo
		- Unmount all rgfs dirs

- VM is shutdown and logs and timings are collected
- Worker notifies the Builder
- Builder calls 'builder_done' function which will trigger 'wh_build_job_done' event


== Scenario 2 ==
- User, from the web interface, edits a pkg_repo/subrepo:
	- 'pkg_subrepo_edit' event is triggered (user edited a pkg subrepo)
		triggers 'rg_pkg_subrepo_event_edit' event
	- or 'rg_pkg_subrepo_event_pkg_repo_changed' event is triggered (user edited a pkg repo)
		triggers 'rg_pkg_subrepo_event_edit' event


== Events called from the scenarios ==
- Event 'wh_build_job_done' [function rg_wh_build_job_done]
	If callbacks are present, add events for all of them

- Event 'rg_pkg_subrepo_event_edit':
	- flag force_regenerate_dotrepo is set to 1 because version was incremented
	- only for environments which already have a dotrepo (no build for empty pkg repos)
	- calls 'pkg_generate_dotrepo_rpm' event for all enabled envs

- Event 'pkg_generate_dotrepo_rpm' [function rg_pkg_event_generate_dotrepo_rpm]:
	- sets 'exec:worker_must_be_global' flag - we do not trust user workers
	- prepares a fake pkg_maps from the pkg_repo/subrepo passed in the event
	- calls 'rg_pkg_prepare_for_rgfs' function
	- calls 'rg_pkg_prepare_for_dotrepo' function
	- calls 'rg_builder_add'

- Event 'pkg_subrepo_regenerate' [function rg_pkg_subrepo_event_regenerate]:
	- 'uid' is set to 0
	- for each subrepo passed in the event a fake pkg_maps is created
	- calls 'rg_pkg_prepare_for_rgfs' function
	- calls 'rg_pkg_prepare_for_dotrepo' function
	- calls 'rg_builder_add'

- Function 'rg_pkg_prepare_for_dotrepo':
	- it avoids not enabled environments (state::distros)
	- for each pkg mapping:
		- if (event uid != pkg_repo uid) skip (we do not allow a user to influence other repos)
			TODO: what if event uid is 0?!
		- if (!force_regenerate_dotrepo && we already generated the last version of dotrepo) skip
		- adds files which will go in /etc/yum.repos.d and gpg keys
	- it will add an event callback: 'pkg_generate_dotrepo_rpm_callback'

- Event 'rg_pkg_subrepo_update_distro_info' [function rg_pkg_event_generate_dotrepo_rpm_callback function]
	it calls: rg_pkg_subrepo_update_distro_info and
	triggers pkg_subrepo_regenerate if ev[status][pkg_subrepo_dirty'] is present
		this flag is set when build_repo.sh is copying something to +pending

- Event 'pkg_generate_dotrepo_rpm_callback' [function rg_pkg_event_generate_dotrepo_rpm_callback]:
	- called when a dotrepo was done
	- for each (subrepo, ver), call 'rg_pkg_subrepo_update_distro_info'
	- if 'status:pkg_subrepo_dirty' is present, trigger 'pkg_subrepo_regenerate' event
		Set by the 'worker', based on /root/build2/pkg_subrepo_dirty file
			Set by build_repo.sh when some .rpm are copied on rgfs


== old ==
- The .spec file is found and .rpm files are generated.
- The .rpm files are moved to '+pending folder'.
	We do not create directly the repo because we do not trust the
	environment anymore.
- The finish of the job will trigger the rebuild of the repo.
- If a "dotrepo" .rpm file (containing files which will be put in
	/etc/yum.repos.d) is not built for that repo/distro/major/arch
	the build is triggered.
== old end ==