Add Contributing.md

[kara-mela]

Motivation

Currently, PaNET does not fulfill the community standards for GitHub repositories, e.g. missing license, code of conduct, contributing, security policy, pull request template.

Modification

A CONTRIBUTING.md file has been added.

Result
Improving the overall quality of the repository.

Contributes to #324

[majumdararn]

Under Install ROBOT (necessary only once), one could add:

1. Check whether java is installed using java –version
2. Clone source code of 1.8.1 version (recommended in README) using git clone https://github.com/ontodev/robot.git robot-1.8.1
3. Enter the cloned directory using cd robot-1.8.1
4. Check if maven is installed using mvn –help
5. If already installed, skip this. If not, sudo apt update; sudo apt install -y maven
6. Build with maven using mvn install
7. Check installation using java -jar bin/robot.jar --help
8. Add following lines in .bashrc

## add robot to path 
export PATH=$PATH:$CLONE_DIR/robot-1.8.1/bin 

9. Check if robot works using robot --help

[majumdararn]

I have two comments:

1. Could we add precise instructions on how to add a new term or dependency?
2. Could we add a link to this file in the README?

[paulmillar]

We perhaps should also mention the panet-build container image that provides a complete environment for building PaNET. This is likely an easy way for someone to get started.

[paulmillar]

This reads like how to contribute when targeting code -- we don't really have any code.

Perhaps a better section would be how to request a new experimental technique, how to enhance an existing term, how to report a concern/problem, ...

[kara-mela]

Thanks for the input!

• I added @majumdararn instructions to install ROBOT.
• I added rough instructions to add a new term. The detailed instructions are still work in progress, see Creating a PaNET Best Practice document #292.
• I added instructions to enhance a term or report other issues.
• I added a link from the README.md to CONTRIBUTING.md, at the same time, I deleted duplicate content from README.md

Unfortunately, I don't know how to include the panet-build information here. @paulmillar could you please elaborate?

[thamnos]

I'm afraid it's not yet fool proof enough... Is there maybe a step missing in the beginning where I have to fork the project into my own github space? I'm failing with the current instructions at the following step:

sbusch@xps13:/tmp$ git clone https://github.com/ExPaNDS-eu/ExPaNDS-experimental-techniques-ontology
Cloning into 'ExPaNDS-experimental-techniques-ontology'...
remote: Enumerating objects: 1017, done.
remote: Counting objects: 100% (427/427), done.
remote: Compressing objects: 100% (223/223), done.
remote: Total 1017 (delta 300), reused 204 (delta 204), pack-reused 590 (from 1)
Receiving objects: 100% (1017/1017), 1.69 MiB | 6.59 MiB/s, done.
Resolving deltas: 100% (478/478), done.
sbusch@xps13:/tmp$ cd ExPaNDS-experimental-techniques-ontology
sbusch@xps13:/tmp/ExPaNDS-experimental-techniques-ontology$ ls
CHANGELOG.md  docs  examples  LICENSE  logo  meetings  README.md  source
sbusch@xps13:/tmp/ExPaNDS-experimental-techniques-ontology$ git remote add upstream git@github.com:ExPaNDS-eu/ExPaNDS-experimental-techniques-ontology.git
sbusch@xps13:/tmp/ExPaNDS-experimental-techniques-ontology$ git fetch upstream
The authenticity of host 'github.com (140.82.121.4)' can't be established.
ED25519 key fingerprint is SHA256:blablabla.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'github.com' (ED25519) to the list of known hosts.
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

[kara-mela]

Let's try the following steps.

• Check if you have an ssh key: ls -a1 ~/.ssh produces a list. Does it contain id_ed25519 or id_rsa or something similar?
• If not, create an ssh key using your mail address connected to github: ssh-keygen -t ed25519 -C "your_email@example.com"
• Add the ssh key to the ssh agent: eval "$(ssh-agent -s)" and ssh-add ~/.ssh/id_ed25519
• Add the ssh key to github:
  • Copy your public key to the clipboard
  • Go to GitHub, click your profile picture → Settings → SSH and GPG keys → New SSH Key. Paste your key and save.
• Test the ssh connection to github: ssh -T git@github.com
• Configure git to use ssh: git remote set-url upstream git@github.com:username/repo.git
• Retry: git fetch upstream

If this is not working, we need to get some more experienced people involved ;)

[thamnos]

One step further, thank you!
Now I'm stuck again though. I've made a change, git added the file, and git commited it. However, when I try to push, it comes back asking for my username and password again instead of using my SSH key:

git push origin HEAD
Username for 'https://github.com': .....

git config -l
user.name=...
user.email=...
credential.helper=store
pull.rebase=true
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
remote.origin.url=https://github.com/ExPaNDS-eu/ExPaNDS-experimental-techniques-ontology
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
branch.master.remote=origin
branch.master.merge=refs/heads/master
remote.upstream.url=git@github.com:ExPaNDS-eu/ExPaNDS-experimental-techniques-ontology.git
remote.upstream.fetch=+refs/heads/*:refs/remotes/upstream/*

[paulmillar]

By the look for things, you're using the https:// remote connection. This is fine, but it'll ask you for your username and password. You have a number of options:

1. save your password as git configuration (not a great option),
2. get an OAuth/API key and use that (better)
3. use the ssh-based remote connection; these start git@github.com:. I think this option becomes available once you've logged into GitHub.

I generally use 3., but 2. is also a valid choice. I would avoid 1.

[thamnos]

Right, let's go with option 3.
Is that achieved by changing line 103 from git push origin HEAD to git push upstream HEAD?

Also, in @kara-mela's last comment, there is a "Configure git to use ssh: git remote set-url upstream git@github.com:username/repo.git", but the contributing.md does not contain such a line. Is it covered by the git remote add upstream command or does it have to be done in addition to it?

[paulmillar]

The distinctions between git push origin HEAD/git push upstream HEAD and between https/git is actually orthogonal.

When working with a git service (e.g., GitHub or GitLab) it's pretty-much guaranteed that you don't have direct write access to the repository. To allow collaboration, these services (GitHub) allow people to make their own complete copy of the repo, called a fork (a process called "forking"). You make changes in your own copy and offer those changes, so people choose to accept your changes.

Git makes working with multiple independent copies relatively easy.

By convention, people name their own (personal) copy of the repo origin and the original upstream. These are the names on your laptop/desktop. Just to reiterate, origin is the name (on your laptop/desktop) of the repo (in GitHub) you can modify however you want; upstream is the name (on your laptop/desktop) of the repo (in GitHub) that you can't directly change.

The choice of names doesn't actually matter; you could call them my-fork and central if you prefer.

To contribute a change, you create a branch on your laptop/desktop, commit one (or more) changes, push that branch into origin (the repo in GitHub you can modify), finally create a pull-request against a branch in upstream (typically the master branch).

The question of https: vs git: is about how your client (on you computer) is interacting with one of these repos within GitHub. For each remote, there's two kinds of interaction: reading (fetch) and writing (push), so there's actually two URLs. These are almost always the same, so you almost certainly don't have to worry about this.

Just for reference, here's the origin and upstream configuration for PaNET on my laptop:

$ git remote -v|grep ^[ou]
origin  git@github.com:paulmillar/ExPaNDS-experimental-techniques-ontology.git (fetch)
origin  git@github.com:paulmillar/ExPaNDS-experimental-techniques-ontology.git (push)
upstream        git@github.com:ExPaNDS-eu/ExPaNDS-experimental-techniques-ontology.git (fetch)
upstream        git@github.com:ExPaNDS-eu/ExPaNDS-experimental-techniques-ontology.git (push)
$ 

The origin remote is my personal fork of PaNET. You can see my GitHub account (paulmillar) in the URL. The upstream remote is the central repo.

I'm using grep in the command because my setup is slightly more complicated. It's actually has four remotes:

$ git remote -v
melanie git@github.com:kara-mela/ExPaNDS-experimental-techniques-ontology.git (fetch)
melanie git@github.com:kara-mela/ExPaNDS-experimental-techniques-ontology.git (push)
origin  git@github.com:paulmillar/ExPaNDS-experimental-techniques-ontology.git (fetch)
origin  git@github.com:paulmillar/ExPaNDS-experimental-techniques-ontology.git (push)
terence git@github.com:terencetan-c/ExPaNDS-experimental-techniques-ontology.git (fetch)
terence git@github.com:terencetan-c/ExPaNDS-experimental-techniques-ontology.git (push)
upstream        git@github.com:ExPaNDS-eu/ExPaNDS-experimental-techniques-ontology.git (fetch)
upstream        git@github.com:ExPaNDS-eu/ExPaNDS-experimental-techniques-ontology.git (push)
$ 

The melanie remote is Melanie's personal fork of PaNET; terence is Terence's personal fork of PaNET. I don't have write access to these two repos, but I have read access. By having these remotes, I can checkout (== update the files on my laptop) changes from them, if needed. This is very occasionally useful, but probably not for "normal" people :-)

The git remote add command configures git (on you laptop/computer) so it knows about a new remote; this only works if the remote isn't already configured. In contrast, the git remote set-url command updates the URL of an existing remote. So, instead of git remote set-url you could use the two commands git remote remove and git remote add ... but that would involve more typing.

[kara-mela]

During the hackathon on 2026-01-16, we decided to restructure the document. New version is available now.

[thamnos]

The problem described above persists

[kara-mela]

I guess, we need to sit together and try to solve this. The results of this session will be used to improve the document.