Skip to content

Commit fae59cf

Browse files
dalitodalito
committed
Fill how-to-contribute page with contents
1 parent b0ab088 commit fae59cf

1 file changed

Lines changed: 266 additions & 4 deletions

File tree

‎docs/docs_usage/how-to-contribute.md‎

Lines changed: 266 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,270 @@
11
# How to contribute to Voc4Cat?
22

3-
```{todo}
4-
Move and merge documentation on contributing to the vocabulary from [readme](https://github.com/nfdi4cat/voc4cat/blob/main/README.md#contributing-to-vocabularies)
5-
and {ref}`guidelines-v2.0 <docs_usage/published-guidelines-v2:5. contribution step-by-step guide>` to this page.
3+
## Step-by-step contribution guide
64

7-
We should maybe also add a section about how to contribute to this dcoumentation.
5+
The main steps that a community member needs to follow to contribute to
6+
Voc4Cat are illustrated in the diagrams below.
7+
8+
Steps 1-4 are performed only once and are intended to set up the GitHub environment for the contributor.
9+
10+
```{mermaid}
11+
flowchart LR
12+
A1[Step 1<br>Create GitHub<br>account] --> A2[Step 2<br>Access<br>repository] --> A3[Step 3<br>Request<br>ID range] --> A4[Step 4<br>Fork repository<br>set up remotes]
13+
```
14+
15+
The actual vocabulary contribution process involves steps 5-7 which are repeated
16+
with each new submission.
17+
18+
```{mermaid}
19+
flowchart LR
20+
B5[Step 5<br>Get latest Excel template] --> B6[Step 6<br>Edit concepts in Excel] --> B7[Step 7<br>Open PR and iterate]
21+
```
22+
23+
```{admonition} Contribution overview
24+
:class: tip
25+
26+
Below is a compact overview of the contribution flow. Select the tabs that match your preferred way of working, either Git commands or GitHub Web UI.
27+
```
28+
29+
### Initial steps (one-time)
30+
31+
#### Step 1 – Create a GitHub account
32+
33+
This step happens in the browser only. No commands. Visit [github.com](https://github.com/) and create a personal account.
34+
35+
```{caution}
36+
It is essential to use a *personal GitHub account*. Contributing from organization accounts does not work due to GitHub limitations (status Nov-2025, see [discussion](https://github.com/orgs/community/discussions/5634)).
37+
```
38+
39+
#### Step 2 – Access the Voc4Cat repository
40+
41+
While signed in, open the repository of Voc4Cat <https://github.com/nfdi4cat/voc4cat>. Familiarize yourself with the README and existing issues.
42+
43+
Contributing or participating in discussions requires you to be signed in with your personal GitHub account.
44+
45+
#### Step 3 – Request an ID range
46+
47+
You will need unique IDs for each new concept that you want to add to Voc4Cat.
48+
49+
Voc4cat gives each user their personal ID range(s) to pick IDs from.
50+
This way contributions can happen asynchronously without needing additional coordination between users.
51+
52+
While on the Voc4Cat repository page <https://github.com/nfdi4cat/voc4cat>,
53+
54+
- click on *Issues* (top left corner), then
55+
- click on *New issue* (green button on the top right corner)
56+
- finally click on the “*Request a range of IDs*” option.
57+
58+
This opens a dialog window:
59+
60+
- Enter the number of IDs that you need for new concepts.
61+
The number does not have to be exact.
62+
Request enough if you plan several contributions in the future (typical numbers are 10...100).
63+
- Add your *Open Researcher and Contributor ID* ([ORCID identifier](https://orcid.org/)).
64+
This is optional but recommended.
65+
- Add the *Research Organization Registry* ([ROR](https://www.ror.org)) identifier of the organization you work for.
66+
- Add any additional information that you deem necessary such as what you plan to work on.
67+
68+
#### Step 4 – Fork the repository
69+
70+
Copying ("*forking*") Voc4Cat’s repository to your workspace allows modifications independent of the original repository.
71+
Forking is an essential step in GitHub´s collaborative development model.
72+
73+
To fork Voc4Cat, while being logged in,
74+
75+
- Navigate to the [nfdi4cat/voc4cat](https://github.com/nfdi4cat/voc4cat) repository.
76+
- Click on the *Fork* button (top right corner).
77+
78+
After creation, your fork will be available as new repository in your workspace at `https://github.com/<your_username>/voc4cat`.
79+
80+
::::{tab-set}
81+
:::{tab-item} Git commands
82+
:sync: Git commands
83+
To prepare for contributing from your local computer
84+
85+
1. Clone your fork:
86+
87+
```bash
88+
git clone https://github.com/<your_username>/voc4cat.git
89+
```
90+
91+
2. Add "upstream" remote:
92+
93+
```bash
94+
cd voc4cat
95+
git remote add upstream https://github.com/nfdi4cat/voc4cat.git
96+
```
97+
98+
:::
99+
100+
:::{tab-item} GitHub Web UI
101+
:sync: GitHub Web UI
102+
*No action required.*
103+
:::
104+
::::
105+
106+
### Steps for every contribution
107+
108+
#### Step 5 – Get the latest versions
109+
110+
Step 5 is the first of the 3 steps that need to be repeated for each individual contribution.
111+
112+
First, **download the current version of Voc4Cat as xlsx (Excel) file**.
113+
Go to the [voc4cat-homepage](https://nfdi4cat.github.io/voc4cat/), and download the file by clicking on the middle *Vocabulary card*
114+
(or use this direct [download link](https://nfdi4cat.github.io/voc4cat/dev/voc4cat.xlsx)).
115+
116+
Second you have to **update your voc4cat-fork**.
117+
While not absolutely essential it is recommended that the vocabulary stored in the repository as RDF/turtle matches the concepts stored in the downloaded xlsx file.
118+
119+
::::{tab-set}
120+
:::{tab-item} Git commands
121+
:sync: Git commands
122+
3. Fetch upstream:
123+
- `git fetch upstream`
124+
5. Ensure local main tracks upstream main:
125+
- `git checkout main`
126+
- `git pull upstream main`
127+
128+
129+
From your cloned repo root:
130+
131+
1. Update local main:
132+
- `git checkout main && git pull upstream main`
133+
2. Create feature branch for the contribution:
134+
- `git checkout -b feat/<short-topic>`
135+
3. Download fresh template (overwriting old if present):
136+
- Use browser to download https://nfdi4cat.github.io/voc4cat/dev/voc4cat.xlsx
137+
4. Place file at `inbox-excel-vocabs/voc4cat.xlsx`.
138+
:::
139+
140+
:::{tab-item} GitHub Web UI
141+
:sync: GitHub Web UI
142+
Open your fork of voc4cat <https://github.com/your_username/voc4cat> in the browser.
143+
144+
Press the green "Sync fork" button. If this fails, see troubleshooting.
145+
:::
146+
::::
147+
148+
Get the latest vocabulary as Excel (xlsx) file.
149+
150+
#### Step 6 – Add / edit concepts in Excel
151+
152+
Follow classification & Excel rules above. Ensure each new concept has a broader chain to a top concept.
153+
154+
::::{tab-set}
155+
:::{tab-item} Git commands
156+
:sync: Git commands
157+
Edit the Excel file locally in your spreadsheet program. (Optional future tooling: local validator.) After edits:
158+
159+
1. Stage file:
160+
- `git add inbox-excel-vocabs/voc4cat.xlsx`
161+
2. Commit with informative message (include ID span):
162+
- `git commit -m "voc4cat: add <topic> (IDs ####–####)"`
163+
:::
164+
:::{tab-item} GitHub Web UI
165+
:sync: GitHub Web UI
166+
Download the template from your branch, edit locally, then drag & drop updated
167+
`voc4cat.xlsx` into `inbox-excel-vocabs/` on your feature branch page. Add
168+
commit message: `voc4cat: add <topic> (IDs ####–####)`.
169+
For subsequent revisions repeat download → edit → upload.
170+
:::
171+
::::
172+
173+
**Excel file rules**
174+
175+
- Location: `inbox-excel-vocabs/voc4cat.xlsx` (or additional files if split; keep naming consistent).
176+
- Do not rename arbitrarily.
177+
- One conceptual change set per PR (keep focused).
178+
- Provide clear definition text (concise, domain-relevant).
179+
- Download the current Excel template: https://nfdi4cat.github.io/voc4cat/dev/voc4cat.xlsx
180+
- Do not change the Excel template structure (sheet names, header row, column order).
181+
182+
```{seealso}
183+
For deeper methodological guidance see the published guidelines section on
184+
contribution steps.
185+
```
186+
187+
#### Step 7 – Open & iterate on the Pull Request
188+
189+
```{warning}
190+
Do not create PRs from your fork's main branch. Always work on a feature branch (created in Step 5).
191+
```
192+
193+
```{tip}
194+
Before starting work, sync your fork/clone with upstream `main` to avoid conflicts.
8195
```
196+
197+
::::{tab-set}
198+
:::{tab-item} Git commands
199+
:sync: Git commands
200+
Push branch (first time):
201+
202+
- `git push -u origin feat/<short-topic>`
203+
204+
Open PR in browser (compare: your branch; base: nfdi4cat/voc4cat `main`). Use
205+
template & checklist.
206+
For updates: edit Excel, commit, push again:
207+
208+
- `git add inbox-excel-vocabs/voc4cat.xlsx`
209+
- `git commit -m "update: refine definitions (IDs ####–####)"`
210+
- `git push`
211+
:::
212+
:::{tab-item} GitHub Web UI
213+
:sync: GitHub Web UI
214+
Click “Compare & pull request” after pushing branch or use “New pull request”.
215+
Fill description: summary, ID range, confirmation of broader chains, no TTL
216+
edits. Mark checklist. Use Draft PR for early feedback. To update: re-upload
217+
improved Excel to same path; commit automatically appears in PR.
218+
After approval a maintainer merges; CI generates TTL & HTML preview.
219+
:::
220+
::::
221+
222+
**PR checklist**
223+
224+
- [ ] File is `inbox-excel-vocabs/voc4cat.xlsx` (name and path unchanged)
225+
- [ ] IDs are within my allocated range
226+
- [ ] Each concept has prefLabel, definition, and a broader chain to a top concept
227+
- [ ] Contribution is focused/small enough for review (split if needed)
228+
- [ ] No `.ttl` files edited
229+
- [ ] PR title and description summarize the motivation and scope
230+
231+
```{tip}
232+
Open your PR as "Draft" if you want early feedback. Mention any specific questions. Curators are informed automatically about every new PR.
233+
```
234+
235+
The xlsx file is ephemeral and never stored in the repository. It is generated from the RDF/turtle files.
236+
237+
**Review priorities**
238+
239+
1. Classification completeness
240+
2. ID correctness
241+
3. Scope / definition clarity
242+
4. Optional enhancements (examples, altLabels)
243+
244+
#### After merge
245+
246+
CI builds and publishes updated development version. Verify your concepts
247+
using:
248+
249+
- HTML preview: https://nfdi4cat.github.io/voc4cat/dev/voc4cat/index.html
250+
- Download new Excel if planning further contributions.
251+
252+
```{tip}
253+
Open follow-up issue for any post-merge adjustments; do not edit generated Turtle directly.
254+
```
255+
256+
## Contributing to the homepage
257+
258+
We use [Sphinx](https://www.sphinx-doc.org/) as documentation builder with the [furo](https://github.com/pradyunsg/furo) theme
259+
and [MySt](https://mystmd.org/) to support extended markdown.
260+
261+
To get an overview about the styling features supported visit the [furo theme documentation](https://pradyunsg.me/furo/kitchen-sink/)
262+
or the [MyST authoring documentation](https://mystmd.org/guide/typography).
263+
264+
To help you checking your changes before making a pull request, we provide instructions how to [build the documentation locally](../docs_maintenance/creating-docs-locally.md).
265+
266+
## Questions or issues?
267+
268+
- Vocabulary discussions: <https://github.com/nfdi4cat/voc4cat/issues>
269+
- Tooling improvements (voc4cat-tool): <https://github.com/nfdi4cat/voc4cat-tool/issues>
270+
- Template feedback (voc4cat-template): <https://github.com/nfdi4cat/voc4cat-template/issues>

0 commit comments

Comments
 (0)