README: Add howto to create a new project.

README.md

@@ -64,3 +64,14 @@ the images.
 ▶ [manifest Pipeline][8]
 
 [8]: docs/manifest-pipeline.md
+
+<!----------------------------------------------------------------------------->
+# Add new project to be handled by the pipeline
+<!----------------------------------------------------------------------------->
+
+See this chapter for the steps needed to setup a new project using the pipeline.
+
+▶ [Add project using the Pipeline][9]
+
+[9]: docs/add-new-project-to-pipeline.md
+

docs/add-new-project-to-pipeline.md

+<!----------------------------------------------------------------------------->
+# Add a new project using the CI pipeline
+<!----------------------------------------------------------------------------->
+
+The CI script infrastructure allow automatical pipeline builds and integration
+using the complete yocto build system.
+
+To add a new project several steps are needed to make this work together:
+
+
+## Create the project
+
+Just use the new project button in gitlab and prepare the project with some
+source code.
+
+## Configure the new project
+
+In the gitlab UI use the settings:
+
+`Settings->Repository`:
+
+* *Default branch*: Set the Default branch to something useful `main` or `kirkstone`. Mainly this
+  depends if the sourcecode can be reused as it is for different yocto versions
+  or if for example `dunfell` and `kirkstone` need different sources.
+
+* *Protected branch*: Add at least the default branch to the 'protected branches' list.
+  Select 'Allowed to merge' to 'Maintainers' and `Allowed to push` to `No one`
+
+`Settings->Merge requests`:
+
+* *Merge method*: Set to `Fast-forward merge`
+
+* *Squash commits when merging*: Set to `Do not allow`
+
+* *Merge checks*: Set to `Pipelines must succeed`
+
+
+`Settings->CI/CD`:
+
+* *Variables*: Add a variable `INTEGRATION`, that specifies the which branch of
+               this project should be integrated into which branch of the yocto.
+               for example: `main:seco-ne/yocto/manifest:kirkstone`
+               `main`: The default branch of the new project.
+               `seco-ne/yocto/manifest`: The path to the manifest of the yocto 
+                                         project. This might differ for custom
+                                         layers. 
+               `kirkstone`: The branch of the yocto manifest to be used for the
+                            integration.
+               There may be more lines then only one, to integrate into several
+               yoctos or branches.
+
+## Add the new project to the yocto project
+
+### Project referenced by recipe
+
+This part is relevant, if the new repo should be used by a recipe as new package.
+
+Create a new recipe in one of the layers used by the yocto project like 
+`<new-project.bb>`:
+
+```
+SUMMARY = "..."
+DESCRITPTION = "..."
+HOMEPAGE = "https://git.seco.com/seco-ne/<path to the new project>"
+
+LICENSE = "Apache-2.0"
+LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/Apache-2.0;md5=89aea4e17d99a7cacdbeed46a0096b10"
+
+SRCREV = "${AUTOREV}"
+SRC_URI = " \
+  git://git.seco.com/seco-ne/<path to the new project>.git;protocol=https;branch=main;nobranch=1 \
+"
+```
+
+Push this to the layers repo.
+
+### Add a reference in SRCREV.conf
+
+In the 'manifest' directory, use the target branch and modify the `SRCREV.conf`.
+It needs a new line for the new project like:
+
+```
+SRCREV:pn-<new-project> = "<current hash>"
+```
+
+### New layer 
+
+This part is relevant, if the new repo should be used by a yocot layer.
+
+*TODO*
+
+
+## Add the CI code to the new project
+
+### Add submodule .gitlab-ci 
+
+The submodule need to be added with a relative path.
+
+```
+git submodule add ../../yocto/infrastructure/gitlab-ci.git .gitlab-ci
+```
+
+### Add the local .gitlab-ci.yml
+
+```
+---
+# ---------------------------------------------------------------------------------------
+# Include the default CI steps from the gitlab-ci repo
+# ---------------------------------------------------------------------------------------
+include:
+  - project: '${CI_PROJECT_ROOT_NAMESPACE}/yocto/infrastructure/gitlab-ci'
+    ref: 31e5a427d57e2d3cac971a32d18e6274932adb99
+    file: 'manifest-integration.yml'
+
+variables:
+  GITLAB_CI_REVISION: 31e5a427d57e2d3cac971a32d18e6274932adb99
+  BB_RECIPE_NAME: <recipe name, like emc-test-suite.bb>
+```
+
+The `BB_RECIPE_NAME` needs to be adapted, as it is later used to modify the SRCREV.
+