Skip to content

Commit 61b7747

Browse files
hiddedorhout-cbhiddedorhout-cb
authored
Merge pull request #27 from hiddedorhout-cb/docs/update-instructions
Document catalogue update flow with fork & PR instructions
2 parents 8615248 + 32b5093 commit 61b7747

2 files changed

Lines changed: 173 additions & 0 deletions

File tree

‎catalogue/AGENTS.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# AGENTS.md
2+
3+
## Project Purpose
4+
5+
This repository contains a public catalogue of services offered by QTSPs
6+
participating in the WE BUILD project.
7+
8+
The catalogue is intended to:
9+
10+
- present participating QTSPs and their offerings clearly;
11+
- help use case groups discover relevant trust services and capabilities;
12+
- remain simple to publish as a static single-page application on GitHub Pages;
13+
- stay easy to maintain and contribute to, including for contributors with
14+
limited technical experience.
15+
16+
## Product Scope
17+
18+
The catalogue should allow each listed QTSP to present multiple trust services
19+
or functional roles. Examples include:
20+
21+
- QEAA issuer
22+
- verifier
23+
- QES provider
24+
25+
The structure should remain flexible so more service types and capabilities can
26+
be added in the future without major rework.
27+
28+
## Implementation Expectations
29+
30+
- The catalogue should remain a simple static site.
31+
- It should work well as a single-page application hosted on GitHub Pages.
32+
- It should support a dedicated single-QTSP view on top of the current
33+
catalogue functionality.
34+
- Each QTSP should have a stable identifier that can be used in the URL, for
35+
example through a query parameter such as `?id=<qtsp-id>`.
36+
- When a valid QTSP identifier is present in the URL, the application should
37+
show only that QTSP's page or detail view.
38+
- When no QTSP identifier is present, the application should continue to show
39+
the normal catalogue overview.
40+
- The contribution flow should favor low-complexity edits over heavy tooling.
41+
- Prefer approaches that allow non-technical contributors to update content with
42+
minimal risk.
43+
44+
## Contribution Principles
45+
46+
When updating this project:
47+
48+
- prioritize readability over cleverness;
49+
- keep the content structure easy to understand;
50+
- avoid introducing unnecessary build steps or deployment complexity;
51+
- preserve compatibility with GitHub Pages hosting;
52+
- make it straightforward to add, edit, or remove QTSP entries and their
53+
service offerings.
54+
- keep interoperability test results as a single source of truth outside this
55+
catalogue when they are maintained centrally.
56+
57+
## How to update the catalogue
58+
59+
Catalogue content lives in [`catalogue/catalogue.md`](catalogue/catalogue.md), where each
60+
organisation is one `##` section, ordered alphabetically by name. Edits to
61+
`index.html` are not needed — the page renders the markdown at load time.
62+
63+
Contributors typically do not have write access, so changes are submitted via a
64+
**fork and pull request** against the upstream repository
65+
`webuild-consortium/wp4-qtsp-group`:
66+
67+
1. Fork the upstream repo to your own account (the GitHub "Edit this file" pencil
68+
offers to do this automatically, or run `gh repo fork webuild-consortium/wp4-qtsp-group --clone`).
69+
2. Add or edit your organisation's section in `catalogue/catalogue.md`, following
70+
the entry template and keeping entries alphabetical. Use `TODO` for any field
71+
not yet available.
72+
3. Commit on a branch in your fork and open a pull request against `main` of the
73+
upstream repository.
74+
75+
Step-by-step instructions, including the full entry template and both web-UI and
76+
command-line flows, are in [`catalogue/README.md`](catalogue/README.md).
77+
78+
## Content Model Guidance
79+
80+
Each QTSP entry should be able to include:
81+
82+
- a unique id suitable for use in URLs;
83+
- the QTSP name;
84+
- a short description;
85+
- one or more trust services or functionalities;
86+
- a QTSP-level reference to the shared conformance or interoperability test
87+
results source;
88+
- optional supporting details relevant for use case groups.
89+
90+
The model should support one QTSP having several listed services at the same
91+
time.
92+
93+
Interoperability or conformance test results should not be duplicated under
94+
individual attestations when a shared central source exists. In that case, the
95+
catalogue should reference the central source once at QTSP level.

‎catalogue/README.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,84 @@ This directory is the source for the GitHub Pages website.
66

77
The catalogue entries are maintained in [`catalogue/catalogue.md`](./catalogue.md), not in `index.html`.
88

9+
Each organisation is one section in that file. Entries are ordered alphabetically by organisation name. To add or update your organisation, copy the template below and fill it in, keeping the heading levels exactly as shown:
10+
11+
```markdown
12+
## Your Organisation Name
13+
14+
### About
15+
16+
A short description of your organisation.
17+
18+
### Contact Point(s)
19+
20+
- [Name](mailto:you@example.com)
21+
22+
### Trust Services
23+
24+
#### Qualified Electronic Attestation of Attributes (QeAA)
25+
26+
##### Documentation
27+
28+
[Link text](https://example.com/docs)
29+
30+
##### Supported Attestations
31+
32+
###### Hello World Attestation
33+
34+
**Status**
35+
36+
Live
37+
38+
**Description**
39+
40+
A short description of the attestation.
41+
42+
**Supported formats**
43+
44+
- SD-JWT
45+
- mdoc
46+
```
47+
48+
Use `TODO` as a placeholder for anything not yet available.
49+
50+
## How to submit a change (fork & pull request)
51+
52+
You do not have write access to the main repository, so changes are submitted from your own **fork**. This is the step where people most often get stuck, so here it is in full.
53+
54+
The main ("upstream") repository is [`webuild-consortium/wp4-qtsp-group`](https://github.com/webuild-consortium/wp4-qtsp-group).
55+
56+
### Option A — entirely in the GitHub web UI (no tools needed)
57+
58+
1. Open [`catalogue/catalogue.md`](https://github.com/webuild-consortium/wp4-qtsp-group/blob/main/catalogue/catalogue.md) on GitHub.
59+
2. Click the **pencil (✏️) "Edit this file"** icon. GitHub will tell you that you need to fork the repository to propose changes — click **"Fork this repository"**. This creates a copy under your own account (e.g. `your-username/wp4-qtsp-group`).
60+
3. Make your edits in the editor, inserting your organisation in alphabetical order.
61+
4. At the bottom, under **"Commit changes"**, write a short message (e.g. `Add <Organisation> to catalogue`) and choose **"Create a new branch and start a pull request"**.
62+
5. Click **Propose changes**, then **Create pull request**. Confirm the PR targets `webuild-consortium/wp4-qtsp-group` `main` and submit.
63+
64+
### Option B — using Git and the GitHub CLI locally
65+
66+
```bash
67+
# 1. Fork the upstream repo to your account (creates your-username/wp4-qtsp-group)
68+
gh repo fork webuild-consortium/wp4-qtsp-group --clone
69+
cd wp4-qtsp-group
70+
71+
# 2. Create a branch for your change
72+
git checkout -b docs/add-my-organisation
73+
74+
# 3. Edit catalogue/catalogue.md, then commit
75+
git add catalogue/catalogue.md
76+
git commit -m "Add <Organisation> to catalogue"
77+
78+
# 4. Push to your fork and open the pull request against upstream
79+
git push -u origin docs/add-my-organisation
80+
gh pr create --repo webuild-consortium/wp4-qtsp-group --base main --fill
81+
```
82+
83+
Without the GitHub CLI, the equivalent manual steps are: click **Fork** on the upstream repo page, `git clone` your fork, create a branch, commit, `git push`, then open the fork on GitHub and click **"Compare & pull request"**.
84+
85+
A maintainer will review and merge your pull request. Once merged to `main`, the site redeploys automatically (see Deployment below).
86+
987
## Local preview
1088

1189
Use a static server (recommended) so markdown loading works:

0 commit comments

Comments
 (0)