From dc1a80e4b655256066c85c7efa71d7d8543747da Mon Sep 17 00:00:00 2001 From: madbkr Date: Wed, 2 Oct 2024 11:03:26 +0200 Subject: [PATCH 01/16] Add and edit prerequisites --- CONTRIBUTING.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e6710bc6e..18d273daa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,8 +2,10 @@ ### 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).
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. +- Before you change anything, get familiar with the [OEO Workflow](#workflow). ### Contribution of OEO content Please read the [OEO best practices](https://github.com/OpenEnergyPlatform/ontology/wiki/Best-Practice-Principles) carefully. From 48201fca1d0851c93af73001cec235d735f9e199 Mon Sep 17 00:00:00 2001 From: madbkr Date: Wed, 2 Oct 2024 11:04:15 +0200 Subject: [PATCH 02/16] Add welcoming message --- CONTRIBUTING.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 18d273daa..167a5f69a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,8 @@ +## Welcome! + +First of all, thank you for wanting to participate. Any new idea, any reported problem is helpful for the development and most appreciated.
+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). + ## Development ### Prerequisites From 26f6be64d7d18c1020e0a89def46559e51c833c0 Mon Sep 17 00:00:00 2001 From: madbkr Date: Wed, 2 Oct 2024 11:06:02 +0200 Subject: [PATCH 03/16] Move conventions up to where they are first needed --- CONTRIBUTING.md | 102 ++++++++++++++++++++++++------------------------ 1 file changed, 52 insertions(+), 50 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 167a5f69a..b4c19e2d0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,7 +3,6 @@ First of all, thank you for wanting to participate. Any new idea, any reported problem is helpful for the development and most appreciated.
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). -## Development ### Prerequisites @@ -12,6 +11,58 @@ To get started quickly, there are some prerequisities that you need to fullfill. - Every other Thursday (even weeks) an online [OEO developer meeting](https://github.com/OpenEnergyPlatform/ontology/wiki/oeo-dev-meeting-plan) takes place. - Before you change anything, get familiar with the [OEO Workflow](#workflow). +## Development + +### 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).
+With `--amend` you can even add/modify changes to the commit. + + ### Contribution of OEO content Please read the [OEO best practices](https://github.com/OpenEnergyPlatform/ontology/wiki/Best-Practice-Principles) carefully. @@ -147,55 +198,6 @@ 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).
-With `--amend` you can even add/modify changes to the commit. - ### Communicate From 95fd35551f2fe8d8aa5ed692c9424933b36c146f Mon Sep 17 00:00:00 2001 From: madbkr Date: Wed, 2 Oct 2024 11:08:28 +0200 Subject: [PATCH 04/16] Move emoji table back up --- CONTRIBUTING.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b4c19e2d0..19aa2de80 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,6 +13,16 @@ To get started quickly, there are some prerequisities that you need to fullfill. ## Development +### Contribution of OEO content +Please read the [OEO best practices](https://github.com/OpenEnergyPlatform/ontology/wiki/Best-Practice-Principles) carefully. + +| Emoji ... | ... symbolizes tool ... | ...which is used for ... | +|:------------------------:|:-----------------------:| ---------------------------------------------------------- | +| 🔶
*orange diamond* | git | keeping code in sync between your PC and online-repository | +| 🐙 
*octopus* | github | discussions and reviews | +| 📙 
*orange book* | protégé | changing the ontology | +| 📝 
*memo* | text editor | changing the ontology as well as other files + ### Conventions for git and GitHub 🔶 Naming convention for branches @@ -61,17 +71,7 @@ git commit --amend ``` to edit the commit message of your latest commit (provided it is not already pushed on the remote server).
With `--amend` you can even add/modify changes to the commit. - - -### Contribution of OEO content -Please read the [OEO best practices](https://github.com/OpenEnergyPlatform/ontology/wiki/Best-Practice-Principles) carefully. - -| Emoji ... | ... symbolizes tool ... | ...which is used for ... | -|:------------------------:|:-----------------------:| ---------------------------------------------------------- | -| 🔶
*orange diamond* | git | keeping code in sync between your PC and online-repository | -| 🐙 
*octopus* | github | discussions and reviews | -| 📙 
*orange book* | protégé | changing the ontology | -| 📝 
*memo* | text editor | changing the ontology as well as other files | + | ### Workflow From a6d6ac5950e3c72228fc22c22f48a22d39641531 Mon Sep 17 00:00:00 2001 From: madbkr Date: Wed, 2 Oct 2024 11:11:16 +0200 Subject: [PATCH 05/16] Make headlines more accessable for newcomers and add table of contents --- CONTRIBUTING.md | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 19aa2de80..71e4c9ed5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,19 @@ +## Table of Contents + +- [Welcome](#Welcome)
+ - [Prerequisites](#Prerequisites)
+- [Development](#development)
+ - [Getting Started](#getting-started)
+ - [Conventions for git and GitHub](#conventions-for-git-and-github)
+ - [Workflow](#workflow)
+ - [Communicate your Ideas or Concerns](#communicate-your-ideas-or-concerns)
+ - [Make Changes to the OEO](#make-changes-to-the-oeo)
+ - [Wait for Review of your Changes](#wait-for-review-of-your-changes)
+ - [Merge your Changes after Approval](#merge-your-changes-after-approval)
+ - [Fixing merge conflicts in git](#fixing-merge-conflicts-in-git)
+ - [Communicate](#communicate)
+ + ## Welcome! First of all, thank you for wanting to participate. Any new idea, any reported problem is helpful for the development and most appreciated.
@@ -13,7 +29,7 @@ To get started quickly, there are some prerequisities that you need to fullfill. ## Development -### Contribution of OEO content +### Getting Started Please read the [OEO best practices](https://github.com/OpenEnergyPlatform/ontology/wiki/Best-Practice-Principles) carefully. | Emoji ... | ... symbolizes tool ... | ...which is used for ... | @@ -79,7 +95,7 @@ With `--amend` you can even add/modify changes to the commit. 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 @@ -99,7 +115,7 @@ by [Vincent Driessen](https://nvie.com/posts/a-successful-git-branching-model/). 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. -**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) @@ -147,7 +163,7 @@ by [Vincent Driessen](https://nvie.com/posts/a-successful-git-branching-model/). 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. @@ -163,7 +179,7 @@ by [Vincent Driessen](https://nvie.com/posts/a-successful-git-branching-model/). 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. -**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. From 04c6691bfcc595c9302eee25948d178d0082645e Mon Sep 17 00:00:00 2001 From: madbkr Date: Wed, 2 Oct 2024 11:12:56 +0200 Subject: [PATCH 06/16] Replace term tracker item with annotation --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 71e4c9ed5..47adeb4fd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -159,7 +159,7 @@ 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.). 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. 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. @@ -172,9 +172,9 @@ 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 #`) - 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 `(#)` -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) + ![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. From 5f9c2ccacaac9c705a549787969d44672a645b48 Mon Sep 17 00:00:00 2001 From: madbkr Date: Wed, 2 Oct 2024 12:14:36 +0200 Subject: [PATCH 07/16] Improve readability and some flavor text --- CONTRIBUTING.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 47adeb4fd..8a93f5988 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,13 +24,13 @@ To get started quickly, there are some prerequisities that you need to fullfill. - 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).
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. +- 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 ### Getting Started -Please read the [OEO best practices](https://github.com/OpenEnergyPlatform/ontology/wiki/Best-Practice-Principles) carefully. +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 ... | |:------------------------:|:-----------------------:| ---------------------------------------------------------- | @@ -78,6 +78,7 @@ 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 +- 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) @@ -113,7 +114,10 @@ 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.
+ 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. #### Make Changes To the OEO @@ -159,7 +163,8 @@ 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 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. + **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 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. 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. @@ -175,15 +180,16 @@ by [Vincent Driessen](https://nvie.com/posts/a-successful-git-branching-model/). 9. 📙 Add [term tracker annotations](https://github.com/OpenEnergyPlatform/ontology/wiki/Term-Tracker-Annotation) to the main changed classes of the ontology ![img](https://github.com/user-attachments/assets/70b0a061-f852-4567-9e1f-146f6fc04ed4) -10. 🔶 stage, commit and push the changes of steps 7 and 8 +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.
+ 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. #### 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`. ### Fixing merge conflicts in git From 56ce4f65151d58e3fb6a4456c594e8e2651f90e9 Mon Sep 17 00:00:00 2001 From: madbkr Date: Wed, 2 Oct 2024 12:36:58 +0200 Subject: [PATCH 08/16] Expand the collaboration section --- README.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index efa6a3b48..630d53665 100644 --- a/README.md +++ b/README.md @@ -48,13 +48,27 @@ We recommend to use the software [Protégé](https://protege.stanford.edu/) to o ## Collaboration This is an interdisciplinary open source project, help is always welcome.
-Everyone is invited to develop this repository with good intentions. +Everyone with good intentions is invited to develop this repository. -The development of the ontology happens mainly on [GitHub](https://github.com/OpenEnergyPlatform/ontology) and is supplemented by regular (online) developer meetings to review the progress and discuss more complicated topics. - -If you're new to GitHub or ontologies check out our ["How to participate"](https://github.com/OpenEnergyPlatform/ontology/wiki/Welcome!-How-to-participate) article for some first advice and helpful links. +The development of the ontology happens mainly on [GitHub](https://github.com/OpenEnergyPlatform/ontology) and is supplemented by regular (online) [developer meetings](https://github.com/OpenEnergyPlatform/ontology/wiki/oeo-dev-meeting-plan) to review the progress and discuss more complicated topics.
+If you would like to participate in meetings you can become a team member. Use the [OEP contact form](https://openenergyplatform.org/contact/) and [add yourself as a contributor](https://github.com/OpenEnergyPlatform/ontology/wiki/Add-yourself-as-a-contributor) after approval. +

+If you're new to GitHub or ontologies check out our ["How to participate"](https://github.com/OpenEnergyPlatform/ontology/wiki/Welcome!-How-to-participate) article for some first advice and helpful links. You may also use the [Open Engery Academy course](https://openenergyplatform.github.io/academy/courses/05_ontology/#how-to-become-an-oeo-developer) to get used to the necessary tools and background information. +
The workflow is described in the [CONTRIBUTING.md](https://github.com/OpenEnergyPlatform/ontology/blob/dev/CONTRIBUTING.md) file. Please check it out before you start working on this project. Points that are not clear in the file can be discussed in a [GitHub Issue](https://github.com/OpenEnergyPlatform/ontology/issues/new/choose). Please read the [GitHub Wiki](https://github.com/OpenEnergyPlatform/ontology/wiki) for more information about the ontology, its standards, its best practice principles and the BFO classification. +

+Wiki articles that you would be most helpflul to a beginner are: +- [How to Participate](https://github.com/OpenEnergyPlatform/ontology/wiki/Welcome!-How-to-participate) +- [Best Practice Principles](https://github.com/OpenEnergyPlatform/ontology/wiki/Best-Practice-Principles) including subsections +- [BFO Upper Ontology](https://github.com/OpenEnergyPlatform/ontology/wiki/BFO-Upper-Ontology-Classes) including subsections +- [Explaination on Mass Nouns](https://github.com/OpenEnergyPlatform/ontology/wiki/Explanation-on-mass-nouns) +- [Handeling Ambiguous Terms](https://github.com/OpenEnergyPlatform/ontology/wiki/Handling-ambiguous-terms) +- [Use Protégé to Change the Ontology](https://github.com/OpenEnergyPlatform/ontology/wiki/How-to-use-prot%C3%A9g%C3%A9-to-change-the-ontology) +- [Term Tracker Annotation](https://github.com/OpenEnergyPlatform/ontology/wiki/Term-Tracker-Annotation) +
+... as well as the [CONTRIBUTING.md](https://github.com/OpenEnergyPlatform/ontology/blob/dev/CONTRIBUTING.md). + ## Teams Experts in ontology engineering, economy and energy-system modelling work together collaboratively.
From b728d11e9440963f1c0db53dd5259ac4ffba3873 Mon Sep 17 00:00:00 2001 From: madbkr Date: Wed, 2 Oct 2024 13:48:13 +0200 Subject: [PATCH 09/16] Add links to communicate section --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8a93f5988..1ecdcb617 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -223,4 +223,4 @@ In case of conflicts between your branch and `dev` you must solve them either on ### 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 Team section of our [README](https://github.com/OpenEnergyPlatform/ontology/blob/dev/README.md) file. Use the [OEP contact form](https://openenergyplatform.org/contact/) if you want to become a team member. From b9989056378ef976d652b272f7da4ff911d08800 Mon Sep 17 00:00:00 2001 From: madbkr Date: Fri, 4 Oct 2024 10:05:20 +0200 Subject: [PATCH 10/16] Update changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2998de545..f46605fe9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,6 +34,7 @@ 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) ### Obsoletion - economic value, has economic value, economic value (#1931) From 3dff6d221c9894018a8ad8d11f15794f8f4fd6a9 Mon Sep 17 00:00:00 2001 From: madbkr <92733183+madbkr@users.noreply.github.com> Date: Wed, 9 Oct 2024 10:03:28 +0200 Subject: [PATCH 11/16] Update CONTRIBUTING.md Co-authored-by: stap-m <38690039+stap-m@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1ecdcb617..57a571b7a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -74,7 +74,7 @@ Examples of branch names : `feature-43-add-new-ontology-class` or `feature-711-b 🔶 Commit messages -Try to follow esxisting conventions for 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 From c0f25d27e3fe48e26fc67f65809e79d2b8e690b2 Mon Sep 17 00:00:00 2001 From: madbkr <92733183+madbkr@users.noreply.github.com> Date: Fri, 11 Oct 2024 10:14:54 +0200 Subject: [PATCH 12/16] Update CONTRIBUTING.md as suggested Co-authored-by: Colin --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 57a571b7a..fbe4035b6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -183,7 +183,7 @@ by [Vincent Driessen](https://nvie.com/posts/a-successful-git-branching-model/). 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. + 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 your Changes after Approval From df9693e3a85259c548b5c7eac87c16976b03d0ec Mon Sep 17 00:00:00 2001 From: madbkr Date: Fri, 11 Oct 2024 10:22:13 +0200 Subject: [PATCH 13/16] Add link to article about merging typed --- CONTRIBUTING.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fbe4035b6..277bd3836 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -190,6 +190,9 @@ by [Vincent Driessen](https://nvie.com/posts/a-successful-git-branching-model/). 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`. + +**Hint** +GitHub has three versions of merging: 'Create a merge commit', 'Squash and merge' and 'Rebase and merge'. All tree are explaines 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) In general you are fine just keeping the default option but either option is feasible. ### Fixing merge conflicts in git From 6455e8c321cca7b905c7c0afcd24f201e3caafcb Mon Sep 17 00:00:00 2001 From: madbkr <92733183+madbkr@users.noreply.github.com> Date: Fri, 11 Oct 2024 10:22:34 +0200 Subject: [PATCH 14/16] Update CONTRIBUTING.md Co-authored-by: Colin --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 277bd3836..75c79f66b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -226,4 +226,4 @@ In case of conflicts between your branch and `dev` you must solve them either on ### Communicate -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 Team section of our [README](https://github.com/OpenEnergyPlatform/ontology/blob/dev/README.md) file. Use the [OEP contact form](https://openenergyplatform.org/contact/) if you want to become a team member. +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. From 07e83add74e15c0094631f8bf59dd7aa4c1212ac Mon Sep 17 00:00:00 2001 From: madbkr Date: Fri, 11 Oct 2024 10:40:19 +0200 Subject: [PATCH 15/16] Fix typo --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 75c79f66b..f09042db1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -192,7 +192,8 @@ by [Vincent Driessen](https://nvie.com/posts/a-successful-git-branching-model/). 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`. **Hint** -GitHub has three versions of merging: 'Create a merge commit', 'Squash and merge' and 'Rebase and merge'. All tree are explaines 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) In general you are fine just keeping the default option but either option is feasible. +GitHub has three versions of merging: 'Create a merge commit', 'Squash and merge' and 'Rebase and merge'. All tree 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)
+In general you are fine just keeping the default option but either one is feasible. ### Fixing merge conflicts in git From 8cb86575883825b0cf38cff96518379007344d2b Mon Sep 17 00:00:00 2001 From: madbkr <92733183+madbkr@users.noreply.github.com> Date: Fri, 11 Oct 2024 11:12:27 +0200 Subject: [PATCH 16/16] Fix typo Co-authored-by: Colin --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f09042db1..9f861d619 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -192,7 +192,7 @@ by [Vincent Driessen](https://nvie.com/posts/a-successful-git-branching-model/). 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`. **Hint** -GitHub has three versions of merging: 'Create a merge commit', 'Squash and merge' and 'Rebase and merge'. All tree 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)
+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)
In general you are fine just keeping the default option but either one is feasible.