Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update CONTRIBUTING and README #1808 #1937

Merged
merged 17 commits into from
Oct 11, 2024
Merged

Update CONTRIBUTING and README #1808 #1937

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
dc1a80e
Add and edit prerequisites
madbkr Oct 2, 2024
48201fc
Add welcoming message
madbkr Oct 2, 2024
26f6be6
Move conventions up to where they are first needed
madbkr Oct 2, 2024
95fd355
Move emoji table back up
madbkr Oct 2, 2024
a6d6ac5
Make headlines more accessable for newcomers and add table of contents
madbkr Oct 2, 2024
04c6691
Replace term tracker item with annotation
madbkr Oct 2, 2024
5f9c2cc
Improve readability and some flavor text
madbkr Oct 2, 2024
56ce4f6
Expand the collaboration section
madbkr Oct 2, 2024
b728d11
Add links to communicate section
madbkr Oct 2, 2024
b998905
Update changelog
madbkr Oct 4, 2024
3dff6d2
Update CONTRIBUTING.md
madbkr Oct 9, 2024
c0f25d2
Update CONTRIBUTING.md
madbkr Oct 11, 2024
df9693e
Add link to article about merging typed
madbkr Oct 11, 2024
6455e8c
Update CONTRIBUTING.md
madbkr Oct 11, 2024
07e83ad
Fix typo
madbkr Oct 11, 2024
a34c90d
Merge branch 'dev' into feature-1808-revision-of-contributing-md
madbkr Oct 11, 2024
8cb8657
Fix typo
madbkr Oct 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,10 @@ and the versioning aims to respect [Semantic Versioning](http://semver.org/spec/
- is traded at, trades (#1912)
- replace term tracker item with term tracker annotation (#1922, #1923)
- replace has bearer with characteristic of (#1928)
- rework contributing and readme file (#1937)
- time stamp (#1944)


### Obsoletion
- economic value, has economic value, economic value (#1931)
- has bearer (#1928)
Expand Down
169 changes: 102 additions & 67 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,102 @@
## Development
## Table of Contents

- [Welcome](#Welcome)<br>
- [Prerequisites](#Prerequisites)<br>
- [Development](#development)<br>
- [Getting Started](#getting-started)<br>
- [Conventions for git and GitHub](#conventions-for-git-and-github)<br>
- [Workflow](#workflow)<br>
- [Communicate your Ideas or Concerns](#communicate-your-ideas-or-concerns)<br>
- [Make Changes to the OEO](#make-changes-to-the-oeo)<br>
- [Wait for Review of your Changes](#wait-for-review-of-your-changes)<br>
- [Merge your Changes after Approval](#merge-your-changes-after-approval)<br>
- [Fixing merge conflicts in git](#fixing-merge-conflicts-in-git)<br>
- [Communicate](#communicate)<br>


## Welcome!

First of all, thank you for wanting to participate. Any new idea, any reported problem is helpful for the development and most appreciated. <br>
To get started quickly, there are some prerequisities that you need to fullfill. For a full tutorial, please check out the [Open Energy Academy Course](https://openenergyplatform.github.io/academy/courses/05_ontology/#how-to-become-an-oeo-developer).


### Prerequisites

- [Git](https://git-scm.com/) for version management. [Git How To](https://githowto.com/) provides an introduction into working with Git. Also there is a helpful [Git Cheat Sheet](https://training.github.com/downloads/github-git-cheat-sheet.pdf).
- Please make sure you changed your Protégé settings to [numerical identifiers](https://github.com/OpenEnergyPlatform/ontology/wiki/Numerical-Identifiers) and got a personal ID to add new classes.
- We are using [Git](https://git-scm.com/) for version management. [Git How To](https://githowto.com/) provides an introduction into working with Git. Also there is a helpful [Git Cheat Sheet](https://training.github.com/downloads/github-git-cheat-sheet.pdf).
- We use [Protégé](https://protege.stanford.edu/) to edit the ontology. To get to know Protégé you can use the [Pizza Tutorial](https://www.michaeldebellis.com/post/new-protege-pizza-tutorial). <br> Please make sure you changed your Protégé settings to [numerical identifiers](https://github.com/OpenEnergyPlatform/ontology/wiki/Numerical-Identifiers) and got a [personal ID](https://github.com/OpenEnergyPlatform/ontology/wiki/Add-yourself-as-a-contributor) to add new classes.
- Every other Thursday (even weeks) an online [OEO developer meeting](https://github.com/OpenEnergyPlatform/ontology/wiki/oeo-dev-meeting-plan) takes place. Use the [OEP contact form](https://openenergyplatform.org/contact/) to gain access.
- Before you change anything, get familiar with the [OEO Workflow](#workflow).

## Development

### Contribution of OEO content
Please read the [OEO best practices](https://github.com/OpenEnergyPlatform/ontology/wiki/Best-Practice-Principles) carefully.
### Getting Started
Please read the [OEO best practices](https://github.com/OpenEnergyPlatform/ontology/wiki/Best-Practice-Principles) carefully. The following emojis are used in the text to help you identify the tool you are supposed to use for a specific workstep.

| Emoji ... | ... symbolizes tool ... | ...which is used for ... |
|:------------------------:|:-----------------------:| ---------------------------------------------------------- |
| 🔶 <br/>*orange diamond* | git | keeping code in sync between your PC and online-repository |
| 🐙 <br/>*octopus* | github | discussions and reviews |
| 📙 <br/>*orange book* | protégé | changing the ontology |
| 📝 <br/>*memo* | text editor | changing the ontology as well as other files |
| 📝 <br/>*memo* | text editor | changing the ontology as well as other files

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Line does not end in | as all prev lines.
This does not affect the table, when viewed on the wiki.

### Conventions for git and GitHub

🔶 Naming convention for branches

Follow the [best-practices for git branching naming convention](https://codingsight.com/git-branching-naming-convention-best-practices/).
The convention is `type`-`issue-nr`-`short-description`

**type**

* master / main / stable - includes the current stable version
* dev - includes all current developments
* feature - includes the feature that will be implemented
* release - includes the current version to be released

The majority of the ontology development will be done in `feature` branches.

**issue-nr**

Add the issue number where you describe, discuss and document your development.

**short-description**

Describe shortly what the branch is about. Avoid long and short descriptive names for branches, 2-4 words are optimal.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Avoid long and short descriptive names for branches" sounds unintuitive to me. Like a description might be both short and long at the same time.
I'd change it to "Avoid descriptive names for branches that are either too short or too long".

Other hints:
- Separate words with `-` (minus)
- Do not put your name to the branch name, it's a collaborative project
- Avoid using numbers only
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Do not put your name to the branch name" is grammatically incorrect, if I'm not mistaken,
Change either to "Do not put your name in the branch name" or to "Do not add your name to the branch name".

- Branch names should be precise and informative
- Avoid using capital letters

Examples of branch names : `feature-43-add-new-ontology-class` or `feature-711-branch-naming-convention`

🔶 Commit messages

Try to follow existing conventions for commit messages:
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- Keep the subject line [short](https://chris.beams.io/posts/git-commit/#limit-50) (i.e. do not commit more than a few changes at the time)
- Use [imperative](https://chris.beams.io/posts/git-commit/#imperative) for commit messages
- Start with a [capital letter](https://chris.beams.io/posts/git-commit/#capitalize)
- Do not end the commit message with a [period](https://chris.beams.io/posts/git-commit/#end)


You can use the command
```bash
git commit --amend
```
to edit the commit message of your latest commit (provided it is not already pushed on the remote server). <br>
With `--amend` you can even add/modify changes to the commit.
|

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume this is the missing "|" of line 40.
It seems out of place to me.


### Workflow

The workflow for contributing to this project has been inspired by the workflow described
by [Vincent Driessen](https://nvie.com/posts/a-successful-git-branching-model/).

**Discussion**
#### Communicate your Ideas or Concerns

1. 🐙 Create
[an issue](https://help.github.com/en/articles/creating-an-issue) on
Expand All @@ -39,9 +114,12 @@ by [Vincent Driessen](https://nvie.com/posts/a-successful-git-branching-model/).

[Assign a project](https://help.github.com/en/github/managing-your-work-on-github/adding-issues-and-pull-requests-to-a-project-board#adding-issues-and-pull-requests-to-a-project-board-from-the-sidebar) (default "Issues") to the issue

Discussion about the implementation should take place within the issue. **Important**: Please discuss the proposal within the issue thread **before** starting to work on a solution. For minor changes, which include small changes to improve clarity of definitions and the addition of clarifying annotations, at least one other person from the project team should agree to the proposed change before it is implemented. For major changes, which include adding new entities and restructuring the ontology, at least two other members of the project team need to agree to the change before it is implemented, which should include at least one domain expert and at least one ontology expert. Issues which are contentious, for which it is difficult to reach agreement, should be added to the agenda of the next ontology working group teleconference for discussion to reach agreement amongst the full working group. Subsequent to such discussion, the issue's first thread should be updated with a documented record of the conclusions reached.
Discussion about the implementation should take place within the issue. **Important**: Please discuss the proposal within the issue thread **before** starting to work on a solution. <br>
For minor changes, which include small changes to improve clarity of definitions and the addition of clarifying annotations, at least one other person from the project team should agree to the proposed change before it is implemented. <br>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion:
Add another line break before Important to make it stand out more while reading.
The boldness alone is not as noticeable.

For major changes, which include adding new entities and restructuring the ontology, at least two other members of the project team need to agree to the change before it is implemented, which should include at least one domain expert and at least one ontology expert. <br>
Issues which are contentious, for which it is difficult to reach agreement, should be added to the agenda of the next ontology working group teleconference for discussion to reach agreement amongst the full working group. Subsequent to such discussion, the issue's first thread should be updated with a documented record of the conclusions reached.

**Implementation**
#### Make Changes To the OEO

2. 🔶 Once a solution has been agreed, create a branch from `dev` to work on your issue (see below, the ["Conventions for git and GitHub"](#conventions-for-git-and-github) section)

Expand Down Expand Up @@ -85,11 +163,12 @@ by [Vincent Driessen](https://nvie.com/posts/a-successful-git-branching-model/).
```
If your branch does not exist on the remote server yet, git will provide you with instructions, simply follow them.

Hint: You can create a draft pull request directly after your first commit 🐙, see 7.). Then you get the pull request number and 📙 implement the [term tracker items](https://github.com/OpenEnergyPlatform/ontology/wiki/term-tracker-item) in Protégé. Only after finishing the implementations you can assign reviewers and thus change the state of the PR. Using that workflow, it is clear whether a PR is actually ready for review.
**Hint:** You can create a draft pull request directly after your first commit 🐙, see 7.). <br>
Then you get the pull request number and 📙 implement the [term tracker annotations](https://github.com/OpenEnergyPlatform/ontology/wiki/Term-Tracker-Annotation) in Protégé. Only after finishing the implementations you can assign reviewers and thus change the state of the PR. Using that workflow, it is clear whether a PR is actually ready for review.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

", see 7.)." is hard to read for me.
I suggest changing it to "(see 7).".


6. 🐙 Make sure that all automated tests are successful. This will be indicated by a green or red icon next to your most recent commit. In case an error occured that you don't know how to solve, write a comment in the PR and ask for help from the ontology-expert-team.

**Review**
#### Wait for Review of your Changes

7. 🐙 Submit a pull request (PR)
- Follow the [steps](https://help.github.com/en/articles/creating-a-pull-request) of the github help to create the PR.
Expand All @@ -98,18 +177,23 @@ by [Vincent Driessen](https://nvie.com/posts/a-successful-git-branching-model/).
- Write the corresponding issue number in the pull request so that they are linked. Write it with one of the [special keywords](https://help.github.com/en/github/managing-your-work-on-github/closing-issues-using-keywords) so that the issue will be automatically closed when the PR is merged (example: `Closes #<your issue number>`)
- Add appropriate labels. See [wiki](https://github.com/OpenEnergyPlatform/ontology/wiki/Usage-of-github-labels) for more information.
8. 📝 Describe briefly (i.e. in one or two lines) what you changed in the `CHANGELOG.md` file. End the description by the number in parenthesis `(#<your PR number>)`
9. 📙 Add [term tracker items](https://github.com/OpenEnergyPlatform/ontology/wiki/term-tracker-item) to the main changed classes of the ontology
9. 📙 Add [term tracker annotations](https://github.com/OpenEnergyPlatform/ontology/wiki/Term-Tracker-Annotation) to the main changed classes of the ontology

![img](https://user-images.githubusercontent.com/56925445/78230560-c88ea580-74d1-11ea-921c-a9606c69563f.png)
10. 🔶 stage, commit and push the changes of steps 7 and 8
![img](https://github.com/user-attachments/assets/70b0a061-f852-4567-9e1f-146f6fc04ed4)
10. 🔶 Stage, commit and push the changes of steps 7 and 8
11. 🐙 [Ask](https://help.github.com/en/github/managing-your-work-on-github/assigning-issues-and-pull-requests-to-other-github-users) for review of your PR.
As the issue will have been discussed and agreed on prior to implementation, the purpose of the review step post-implementation is to check that the implementation has been faithful to what was agreed. One or two reviewers may be needed depending on the nature of the change that has been made. If the change involves adding content (A), a domain expert should review the issue. If the change involves restructuring the ontology (B), an ontology expert should review. If the change involves both changes to content and restructuring (B and C), it is best to ask both an ontology expert and a domain expert to review. See the section "Teams tag" of the [README](https://github.com/OpenEnergyPlatform/ontology/blob/dev/README.md) for more information about the expertise of the different team members.
As the issue will have been discussed and agreed on prior to implementation, the purpose of the review step post-implementation is to check that the implementation has been faithful to what was agreed. One or two reviewers may be needed depending on the nature of the change that has been made.<br>
If the change involves adding content (issue type A), a domain expert should review the issue. If the change involves restructuring the ontology (issue type B), an ontology expert should review. If the change involves both changes to content and restructuring (issue types B and C), it is best to ask both an ontology expert and a domain expert to review. See the section "Teams tag" of the [README](https://github.com/OpenEnergyPlatform/ontology/blob/dev/README.md) for more information about the expertise of the different team members.

**Merge**
#### Merge your Changes after Approval

12. 🐙 Check that, after this whole process, your branch does not have conflicts with `dev` (GitHub will prevent you from merging if there are conflicts). In case of conflicts you are responsible for fixing them on your branch before you merge (see below "Fixing merge conflicts" section). If you need help, write a comment in the PR and ask for help from the ontology-expert-team.

13. 🐙 Once approved, merge the PR into `dev` and delete the branch on which you were working. In the merge message on github, you can notify people who are currently working on other branches that you just merged into `dev`, so they know they have to check for potential conflicts with `dev`
13. 🐙 Once approved, merge the PR into `dev` and delete the branch on which you were working. In the merge message on github, you can notify people who are currently working on other branches that you just merged into `dev`, so they know they have to check for potential conflicts with `dev`.

ColinHDev marked this conversation as resolved.
Show resolved Hide resolved
**Hint**
GitHub has three versions of merging: 'Create a merge commit', 'Squash and merge' and 'Rebase and merge'. All three are explained in [this article.](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github) <br>
In general you are fine just keeping the default option but either one is feasible.


### Fixing merge conflicts in git
Expand Down Expand Up @@ -140,56 +224,7 @@ In case of conflicts between your branch and `dev` you must solve them either on
4. 📝 The conflicts have to be [manually](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-using-the-command-line) resolved


### Conventions for git and GitHub

🔶 Naming convention for branches

Follow the [best-practices for git branching naming convention](https://codingsight.com/git-branching-naming-convention-best-practices/).
The convention is `type`-`issue-nr`-`short-description`

**type**

* master / main / stable - includes the current stable version
* dev - includes all current developments
* feature - includes the feature that will be implemented
* release - includes the current version to be released

The majority of the ontology development will be done in `feature` branches.

**issue-nr**

Add the issue number where you describe, discuss and document your development.

**short-description**

Describe shortly what the branch is about. Avoid long and short descriptive names for branches, 2-4 words are optimal.

Other hints:
- Separate words with `-` (minus)
- Do not put your name to the branch name, it's a collaborative project
- Avoid using numbers only
- Branch names should be precise and informative
- Avoid using capital letters

Examples of branch names : `feature-43-add-new-ontology-class` or `feature-711-branch-naming-convention`

🔶 Commit messages

Try to follow esxisting conventions for commit messages:
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- Keep the subject line [short](https://chris.beams.io/posts/git-commit/#limit-50) (i.e. do not commit more than a few changes at the time)
- Use [imperative](https://chris.beams.io/posts/git-commit/#imperative) for commit messages
- Do not end the commit message with a [period](https://chris.beams.io/posts/git-commit/#end)


You can use the command
```bash
git commit --amend
```
to edit the commit message of your latest commit (provided it is not already pushed on the remote server). <br>
With `--amend` you can even add/modify changes to the commit.


### Communicate

Feel free to ask the community if you need help. We are happy to support you.
Feel free to ask the community if you need help. We are happy to support you. If you want to contact specific teammembers or experts, please check out the Teams section of our [README](https://github.com/OpenEnergyPlatform/ontology?tab=readme-ov-file#teams) file. Use the [OEP contact form](https://openenergyplatform.org/contact/) if you want to become a team member.
Loading
Loading