From f47f0b9c5aa9992f72702c7d7e5a61d3e611f49e Mon Sep 17 00:00:00 2001
From: Fabian Arrotin <arrfab@centos.org>
Date: Dec 22 2021 14:02:27 +0000
Subject: Adding some useful cbs/koji error messages and explanations


Signed-off-by: Fabian Arrotin <arrfab@centos.org>

---

diff --git a/docs/cbs.md b/docs/cbs.md
index 82cb32d..e9690e0 100644
--- a/docs/cbs.md
+++ b/docs/cbs.md
@@ -74,7 +74,7 @@ The build target would be `cloud9s-openstack-yoga-el9s` and the tags would be : 
 
 ### Submit a build on CBS
 
-Before being able to submit a build task in koji, one has to be the pkg owner for it for all possible tags, so if you want to become the "owner" of a pkg for your own SIG/group, you can proceed like this (and replace `ACO_name`, `pkg_name` and `basetag` with real values :
+Before being able to submit a build task in koji, one has to be the pkg owner for it for all possible tags, so if you want to become the "owner" of a pkg for your own SIG/group, you can proceed like this (and replace `ACO_name`, `pkg_name` and `basetag` with real values) :
 
 ```
 for level in candidate testing release ; do
@@ -91,6 +91,44 @@ cbs build git+https://git.centos.org/rpms/<pkg_name>.git#<commit_hash>
 !!! note
     you can always submit a test build by adding `--scratch` to the build command as argument : that would really build the pkg but wouldn't make it available anywhere to be used. Please avoid using --scratch though as it consumes resources on the build systems for nothing
 
+### cbs/koji common error messages
+
+#### Build already exists
+
+If you want to submit a build and get the following message, it means that same package/version was already built in koji by someone else :
+
+```
+GenericError: Build already exists
+```
+As a reminder, each build in koji/cbs needs to be unique and follows the ENVR (Epoch Name Version Release) RPM convention.
+So if you need an already built package in your tags (built by another SIG), you can also `tag-build` it to your own tag. (that assumes that you already added the pkg to your tag, per instructions above)
+
+The syntax can be a simple as (pkg_name should be the full rpm package without .rpm at the end): 
+
+```
+cbs tag-build <your_tag-{testing,release,candidate} <pkg_name>-1.0.1.el8 
+```
+
+#### Expired client TLS cert
+
+```
+"Error: [('SSL routines','SSL_shutdown', 'shutdown while in init')]
+```
+That means that your ACO cert (obtained with `centos-cert`) has expired.
+You can always confirm that with `centos-cert -v` :
+
+```
+centos-cert -v
+
+[+] 20211222-11:36 centos-cert -> Verifying if TLS cert is still valid ...
+[+] 20211222-11:36 centos-cert -> Validating TLS cert against ~/.centos-server-ca.cert ...
+/home/<your_username>/.centos.cert: OK
+[+] 20211222-11:36 centos-cert -> [SUCCESS] ~/.centos.cert TLS cert verified by ~/.centos-server-ca.cert CA crt
+[+] 20211222-11:36 centos-cert -> [SUCCESS] Your TLS cert is still valid for [61] days
+
+```
+
+If it expired, just use centos-cert as the first time you used it to obtain a new certificate
 
 ### Promoting packages to mirror network
 
diff --git a/docs/git.md b/docs/git.md
index 0d82c7d..19772da 100644
--- a/docs/git.md
+++ b/docs/git.md
@@ -16,7 +16,7 @@ Let's use the following example : I need to create a branch for pkg centpkg-mini
  *  eventually blob (.tar.gz archive) that will need to be pushed to lookaside cache 
 
 !!! warning
-    To push to lookaside cache you need to have already a local check out from https://git.centos.org/centos-git-common
+    To push to lookaside cache you need to have already a local check out from [https://git.centos.org/centos-git-common](https://git.centos.org/centos-git-common)
 
 ## Pushing first to lookaside cache
 
@@ -95,7 +95,7 @@ d6616b89617914a0dd0fd5cfa06b0afc7a4541c4 SOURCES/centpkg-minimal.tar.gz
 Now that we have pointer to lookaside cache, and also .spec, we can push back to git and we should be able to proceed with the "build-from-git" on cbs.centos.org. Let's commit first :
 
 !!! important
-    Even if your package doesn't contain any source pushed to lookaside cache (like for a package just having some small files in SOURCES/ dir, you *need* to have the .<pkg_name>.metadata package present and pushed in git repository
+    Even if your package doesn't contain any source pushed to lookaside cache (like for a package just having some small files in SOURCES/ dir, you *need* to have the `.<pkg_name>.metadata` package present and pushed in git repository
 
 Here is what the git repository for a pkg should look like :
 
@@ -111,7 +111,7 @@ Here is what the git repository for a pkg should look like :
 
 ```
 
-
+You can now push to to git, as usual:
 
 ```
 # git add <files> # if needed
@@ -119,3 +119,6 @@ git commit -a
 git push origin c7-sig-core # to create the c7-sig-core branch on git.centos.org if not existing yet
 
 ```
+
+Now that we have our sources pushed to both git.centos.org and lookaside cache, we can now proceed with a build in cbs/koji
+