Blame docs/git.md

80c633
# Git/lookaside
2d9703
2d9703
Package sources checked into git.centos.org are in exploded SRPM format. This means that the package working directory should have at least a SPECS/ subdirectory.
2d9703
2d9703
## New Package (from source)
2d9703
2d9703
If the package you'd like to build isn't yet on https://git.centos.org, create first a ticket on https://pagure.io/centos-infra/issues to request the git repo for /rpms/<your_package> to be created
2d9703
2d9703
Once it will be created, it will be possible for you to push to *specific* branches, based on the following rules: c{7,8}-<sig_name>*
2d9703
2d9703
So that means that if I'm member of the sig-core group (in ACO), I'll be able to commit/push to c8-sig-core or c8-sig-core-whatever-I-want branches
2d9703
2d9703
Let's use the following example : I need to create a branch for pkg centpkg-minimal, and I'm member of the sig-core SIG group. We have to push two things to git.centos.org :
2d9703
2d9703
 * .spec files to build a src.rpm
2d9703
 *  eventually blob (.tar.gz archive) that will need to be pushed to lookaside cache 
2d9703
2d9703
!!! warning
f47f0b
    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)
2d9703
2d9703
## Pushing first to lookaside cache
2d9703
2d9703
Let's assume that my pkg centpkg-minimal that I want to build has an archive called centpkg.minimal.tar.gz. To be able to push to lookaside cache, we need the following :
2d9703
2d9703
 * a valid TLS cert (also needed to build on cbs.centos.org) obtained through [centos-cert](../auth/) util
2d9703
 * lookaside_upload script in your $PATH (coming from centos-git-common git repo, see above) 
2d9703
2d9703
This simple script would need some paramters: 
2d9703
2d9703
```
2d9703
lookaside_upload 
2d9703
2d9703
You need to call the script like this : ~/bin/lookaside_upload -arguments
2d9703
2d9703
        -f : filename/source to upload (required, default:none)
2d9703
        -n : package name for that source (requred, default:none, example "httpd")
2d9703
        -b : "branch" where to upload to (required, default:none, example "c7-sig-core")
2d9703
        -h : display this help
2d9703
```
2d9703
2d9703
So back to our example, the pkg name is centpkg-minimal, file is centpkg-minimal.tar.gz and I'm member of the sig-core group, and want to build it for c7, so we'll call it like this :
2d9703
2d9703
```
2d9703
lookaside_upload -f centpkg-minimal.tar.gz -n centpkg-minimal -b c7-sig-core
2d9703
[+] CentOS Lookaside upload tool -> Checking if file already uploaded
2d9703
[+] CentOS Lookaside upload tool -> Initialing new upload to lookaside
2d9703
[+] CentOS Lookaside upload tool -> URL : https://git.centos.org
2d9703
[+] CentOS Lookaside upload tool -> Source to upload : centpkg-minimal.tar.gz 
2d9703
[+] CentOS Lookaside upload tool -> Package name: centpkg-minimal
2d9703
[+] CentOS Lookaside upload tool -> sha1sum: d6616b89617914a0dd0fd5cfa06b0afc7a4541c4
2d9703
[+] CentOS Lookaside upload tool -> Remote branch: c7-sig-core
2d9703
[+] CentOS Lookaside upload tool ->  ====== Trying to upload =======
2d9703
2d9703
################################################################################################################ 100.0%
2d9703
File centpkg-minimal.tar.gz size 15178 CHECKSUM d6616b89617914a0dd0fd5cfa06b0afc7a4541c4 stored OK
2d9703
[+] CentOS Lookaside upload tool -> Validating that source was correctly uploaded ....
2d9703
[+] CentOS Lookaside upload tool -> [SUCCESS] Source should be available at https://git.centos.org/sources/centpkg-minimal/c7-sig-core/d6616b89617914a0dd0fd5cfa06b0afc7a4541c4
2d9703
2d9703
```
2d9703
2d9703
Now that we have uploaded to lookaside cache, we can reference it in our /rpms/centpkg-minimal git repository on git.centos.org, see below 
2d9703
2d9703
2d9703
## Pushing to git.centos.org
2d9703
2d9703
We should already have a local checkout of the git repository for the pkg we'd like to work on. In our case, the git repo url is https://git.centos.org/rpms/centpkg-minimal
2d9703
2d9703
So the way to git clone/pull over ssh is so ssh://git@git.centos.org/rpms/centpkg-minimal.git :
2d9703
2d9703
```
2d9703
git clone ssh://git@git.centos.org/rpms/centpkg-minimal.git
2d9703
Cloning into 'centpkg-minimal'...
2d9703
remote: Counting objects: 15, done.
2d9703
remote: Compressing objects: 100% (11/11), done.
2d9703
remote: Total 15 (delta 2), reused 0 (delta 0)
2d9703
Receiving objects: 100% (15/15), done.
2d9703
Resolving deltas: 100% (2/2), done.
2d9703
```
2d9703
2d9703
!!! important
2d9703
    You can clone over https, but then it wouldn't let you push back to it, as it needs ssh with key verification and based on group membership for acls
2d9703
2d9703
Let's create a new c7-sig-core branch (still based on the assumption that I want to build for c7) :
2d9703
2d9703
```
2d9703
git checkout -b c7-sig-core
2d9703
```
2d9703
a5bc48
You can now create your SPECS/<pkg_name>.spec and add also other text patches under SOURCES/ We still need also to point to /sources/ for the lookaside cache, so we'll use the value of the hash returned when we successfully uploaded to lookaside cache and we'll write a .`<pkg_name>`.metadata file in the root dir that will look like this in our example:
2d9703
2d9703
```
2d9703
d6616b89617914a0dd0fd5cfa06b0afc7a4541c4 SOURCES/centpkg-minimal.tar.gz
2d9703
```
2d9703
2d9703
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 :
2d9703
15677d
!!! important
f47f0b
    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
15677d
15677d
Here is what the git repository for a pkg should look like :
15677d
15677d
```
15677d
.
15677d
├── .<pkg_name>.metadata
15677d
├── SOURCES
15677d
│   ├── <optional_file>
15677d
│   └── <optional_patch>
15677d
└── SPECS
15677d
    └── <pkg_name>.spec
15677d
15677d
15677d
```
15677d
f47f0b
You can now push to to git, as usual:
15677d
2d9703
```
2d9703
# git add <files> # if needed
2d9703
git commit -a 
2d9703
git push origin c7-sig-core # to create the c7-sig-core branch on git.centos.org if not existing yet
2d9703
2d9703
```
f47f0b
f47f0b
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
f47f0b
a5bc48
a5bc48
!!! note
a5bc48
    It's worth knowing that the documented process and structure is the default one, aka `rpmbuild style` layout for how your files/sources should be declared in your git repository/branch. But since 2022-02-21, the `flat layout` (as used also on [Fedora](https://src.fedoraproject.org) dist-git server) can also be used on git.centos.org. You still need to push tarballs to lookaside but you can use the flat layout when importing from Fedora/Epel, and it's purely an opt-in choice, and so not the default one that SIGs are using for years now