Skip to content

Commit 38438a5

Browse files
dmachdmach
committed
Update docs for the new git metadata store
1 parent 8e5e2c4 commit 38438a5

File tree

3 files changed

+164
-0
lines changed

3 files changed

+164
-0
lines changed

‎doc/conf.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,4 +110,5 @@
110110
man_pages = [
111111
("oscrc", "oscrc", "openSUSE Commander configuration file", "openSUSE project <opensuse-buildservice@opensuse.org>", 5),
112112
("git-obs-quickstart", "git-obs-quickstart", "git-obs Quickstart", "openSUSE project <opensuse-buildservice@opensuse.org>", 1),
113+
("git-obs-metadata", "git-obs-metadata", "git-obs Metadata", "openSUSE project <opensuse-buildservice@opensuse.org>", 1),
113114
]

‎doc/git-obs-metadata.rst‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
================
2+
git-obs Metadata
3+
================
4+
5+
After cloning a git repo, we only have a remote URL.
6+
That is not sufficient data for running commands as ``osc build``
7+
and we need to provide information that binds the current checkout
8+
with a build environment that is a project in an OBS instance.
9+
10+
Since we don't want to be providing the values by hand any time we run
11+
``osc`` or ``git-obs``, we need to store the information.
12+
13+
Using ``git config`` turned to be quite cumbersome, because
14+
we need to store relatively large files such as buildinfo and buildconfig.
15+
16+
We ended up using the following locations:
17+
18+
- ``.git/obs/<branch>/meta.json`` for metadata
19+
- ``.git/obs/<branch>/cache/*`` for buildconfig, buildinfo, last_buildroot and any other disposable files
20+
21+
22+
Resolving metadata
23+
==================
24+
25+
The following sections describe the order in which individual fields should be resolved.
26+
The actual code and workflow are different.
27+
All the metadata that should be retrieved from Gitea need to be manually stored
28+
using ``git-obs -G <login> meta pull`` into the local metadata store.
29+
30+
31+
Project checkout
32+
----------------
33+
34+
- ``apiurl``
35+
36+
- read ``obs_apiurl`` from ``.git/obs/<branch>/meta.yaml``
37+
- read ``obs_apiurl`` from ``_manifest`` (should be the default)
38+
- read ``_apiurl`` from ``.osc`` that is next to ``.git``
39+
- read ``obs_apiurl`` from Gitea
40+
41+
- repo: ``obs/configuration``
42+
- file: ``configuration.yaml``
43+
- branch: ``main``
44+
45+
- ``project``
46+
47+
- read ``obs_project`` from ``.git/obs/<branch>/meta.yaml``
48+
- read ``obs_project`` from ``_manifest`` (should be the default)
49+
- read ``_project`` from ``.osc`` that is next to ``.git``
50+
51+
- ``package``
52+
- not applicable
53+
54+
55+
Standalone package checkout
56+
---------------------------
57+
58+
- ``apiurl``
59+
60+
- read ``obs_apiurl`` from ``.git/obs/<branch>/meta.yaml``
61+
- read ``obs_apiurl`` from Gitea
62+
63+
- repo: ``<owner>/_ObsPrj``
64+
- file: ``_manifest``
65+
- branch: matching the current branch of the package
66+
67+
- read ``obs_apiurl`` from Gitea
68+
69+
- repo: ``obs/configuration``
70+
- file: ``configuration.yaml``
71+
- branch: main
72+
73+
- ``project``
74+
75+
- read ``obs_project`` from ``.git/obs/<branch>/meta.yaml``
76+
- read ``obs_project`` from Gitea
77+
78+
- repo: ``<owner>/_ObsPrj``
79+
- file: ``_manifest``
80+
- branch: matching the current branch of the package
81+
82+
- ``package``
83+
84+
- read ``obs_package`` from ``.git/obs/<branch>/meta.yaml``
85+
- read ``repo`` from the current remote URL
86+
- use the directory name
87+
88+
89+
Preconditions for the following scenarios
90+
-----------------------------------------
91+
92+
- Project in the parent directory tree must be detected first.
93+
- The package must be located under a location specified in project's ``_manifest``.
94+
95+
96+
Package checkout in a project checkout (package lives in a submodule)
97+
---------------------------------------------------------------------
98+
99+
- ``apiurl``
100+
101+
- read ``obs_apiurl`` from ``.git/obs/<branch>/meta.yaml``
102+
- read ``obs_apiurl`` from the parent "Project checkout" (see above)
103+
104+
- branch: current
105+
- the project checkout lives in the directory tree above the current git's topdir
106+
107+
- ``project``
108+
109+
- read ``obs_project`` from ``.git/obs/<branch>/meta.yaml``
110+
- read ``obs_project`` from the parent "Project checkout" (see above)
111+
112+
- branch: current
113+
- the project checkout lives in the directory tree above the current git's topdir
114+
115+
- ``package``
116+
117+
- read ``obs_package`` from ``.git/obs/<branch>/meta.yaml``
118+
- read ``repo`` from the current remote URL
119+
- use the directory name
120+
121+
122+
Package directory in a project checkout (package lives in the project)
123+
----------------------------------------------------------------------
124+
125+
- ``apiurl``
126+
127+
- read ``obs_apiurl`` from ``.git/obs/<branch>/meta.yaml``
128+
- read ``obs_apiurl`` from the parent "Project checkout" (see above)
129+
130+
- branch: current
131+
- the project checkout lives in the same git repo
132+
133+
- ``project``
134+
135+
- read ``obs_project`` from ``.git/obs/<branch>/meta.yaml``
136+
- read ``obs_project`` from the parent "Project checkout" (see above)
137+
138+
- branch: current
139+
- the project checkout lives in the same git repo
140+
141+
- ``package``
142+
143+
- use the directory name

‎doc/git-obs-quickstart.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,26 @@ Workflow: Retrieving sources of an existing pull request
156156
157157
git-obs -G opensuse pr checkout PULL_NUMBER [--force]
158158
159+
4. **Set metadata:**
160+
161+
.. note::
162+
This always needs to be done after switching to a new branch.
163+
164+
.. code::
165+
166+
git-obs -G opensuse meta pull
167+
# or
168+
git-obs meta set [--apiurl=...] [--project=...] [--package=...]
169+
170+
171+
5. **Use osc or git-obs with the local checkout**
172+
173+
.. code::
174+
175+
osc build
176+
osc repos
177+
...
178+
159179
160180
Workflow: Querying pull requests
161181
--------------------------------

0 commit comments

Comments
 (0)