Update CONTRIBUTING and README #1808 #1937

madbkr · 2024-10-02T11:28:55Z

Summary of the discussion

Made changes to CONTRIBUTING.md and README.md in order to make it more accessable to new contributors. See Issue #1808

Type of change (CHANGELOG.md)

Update

rework contributing and readme

Workflow checklist

Automation

Closes #1808

PR-Assignee

🐙 Follow the Pull Request Workflow
📝 Update the CHANGELOG.md
📙 Add #'s to term tracker item (this doesn't apply as no changes are made to the oeo)

Reviewer

🐙 Follow the Reviewer Guide
🐙 Provided feedback and show sufficient appreciation for the work done

stap-m

Looks good and it seems to be much more readable now, thanks!

CONTRIBUTING.md

stap-m · 2024-10-07T06:26:55Z

@LillyG901 please take a look at the Reviewer Guide and review this PR as 2nd reviewer.

Co-authored-by: stap-m <38690039+stap-m@users.noreply.github.com>

CONTRIBUTING.md

as suggested Co-authored-by: Colin <colinheidfeld@gmail.com>

Co-authored-by: Colin <colinheidfeld@gmail.com>

ColinHDev

Apart from that typo: Looks good to me :)

CONTRIBUTING.md

Co-authored-by: Colin <colinheidfeld@gmail.com>

LillyG901

Found no semantic issues.
All comments refer to small grammar mistakes or sections that were hard to comprehend for me during my first read through.
They may be ignored, if you don't consider them to be useful changes to the files.

LillyG901 · 2024-10-11T10:45:57Z

README.md

+- [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)
+<br>
+... as well as the [CONTRIBUTING.md](https://github.com/OpenEnergyPlatform/ontology/blob/dev/CONTRIBUTING.md).


When vieved in the wiki Contributing.md does not show up as link(CONTRIBUTING.md), but rather as [CONTRIBUTING.md] (https://github.com/OpenEnergyPlatform/ontology/blob/dev/CONTRIBUTING.md).
I'm unsure what causes this, as copying the line above to show the issue in this comment did not reproduce the issue,

LillyG901 · 2024-10-11T10:46:52Z

CONTRIBUTING.md


 | 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   


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

LillyG901 · 2024-10-11T10:50:51Z

CONTRIBUTING.md

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


"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".

LillyG901 · 2024-10-11T10:53:55Z

CONTRIBUTING.md

+
+Other hints:
+- Separate words with `-` (minus)
+- Do not put your name to the branch name, it's a collaborative project


"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".

LillyG901 · 2024-10-11T10:54:59Z

CONTRIBUTING.md

+```
+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.
+            |


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

LillyG901 · 2024-10-11T10:56:12Z

CONTRIBUTING.md

@@ -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>


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

LillyG901 · 2024-10-11T10:58:23Z

CONTRIBUTING.md

@@ -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>


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

madbkr · 2024-10-11T11:35:38Z

@LillyG901
Since this pull request was already merged we will need a new issue for these changes. I'd be fine with implementing them, they all sound reasonable. I'd only like to talk about it in the meeting on monday first - maybe someone can figure out why the link to contributing doesn't show properly. In my editor it does but here in GitHub it is as you describe.

LillyG901 · 2024-10-11T11:41:40Z

Alright sounds good to me :)

madbkr added 8 commits October 2, 2024 11:03

Add and edit prerequisites

dc1a80e

Add welcoming message

48201fc

Move conventions up to where they are first needed

26f6be6

Move emoji table back up

95fd355

Make headlines more accessable for newcomers and add table of contents

a6d6ac5

Replace term tracker item with annotation

04c6691

Improve readability and some flavor text

5f9c2cc

Expand the collaboration section

56ce4f6

madbkr changed the title ~~Feature-1808-revision-of-contributing-md~~ Update CONTRIBUTING and README #1808 Oct 2, 2024

madbkr self-assigned this Oct 2, 2024

madbkr requested review from stap-m and nelekoehler October 2, 2024 11:36

Add links to communicate section

b728d11

madbkr mentioned this pull request Oct 2, 2024

Update docs and contributing files to facilitate access to OEO for new users #1808

Closed

7 tasks

Update changelog

b998905

madbkr marked this pull request as ready for review October 4, 2024 08:16

stap-m requested a review from LillyG901 October 7, 2024 06:23

stap-m reviewed Oct 7, 2024

View reviewed changes

CONTRIBUTING.md Outdated Show resolved Hide resolved

ColinHDev self-requested a review October 7, 2024 09:12

Update CONTRIBUTING.md

3dff6d2

Co-authored-by: stap-m <38690039+stap-m@users.noreply.github.com>

ColinHDev approved these changes Oct 11, 2024

View reviewed changes

CONTRIBUTING.md Outdated Show resolved Hide resolved

CONTRIBUTING.md Show resolved Hide resolved

CONTRIBUTING.md Outdated Show resolved Hide resolved

madbkr and others added 4 commits October 11, 2024 10:14

Update CONTRIBUTING.md

c0f25d2

as suggested Co-authored-by: Colin <colinheidfeld@gmail.com>

Add link to article about merging typed

df9693e

Update CONTRIBUTING.md

6455e8c

Co-authored-by: Colin <colinheidfeld@gmail.com>

Fix typo

07e83ad

ColinHDev approved these changes Oct 11, 2024

View reviewed changes

CONTRIBUTING.md Outdated Show resolved Hide resolved

madbkr and others added 2 commits October 11, 2024 11:10

Merge branch 'dev' into feature-1808-revision-of-contributing-md

a34c90d

Fix typo

8cb8657

Co-authored-by: Colin <colinheidfeld@gmail.com>

madbkr merged commit 5240d6c into dev Oct 11, 2024
3 checks passed

madbkr deleted the feature-1808-revision-of-contributing-md branch October 11, 2024 09:31

LillyG901 reviewed Oct 11, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update CONTRIBUTING and README #1808 #1937

Update CONTRIBUTING and README #1808 #1937

madbkr commented Oct 2, 2024 •

edited by stap-m

Loading

stap-m left a comment

stap-m commented Oct 7, 2024

ColinHDev left a comment

LillyG901 left a comment

LillyG901 Oct 11, 2024

LillyG901 Oct 11, 2024

LillyG901 Oct 11, 2024

LillyG901 Oct 11, 2024

LillyG901 Oct 11, 2024

LillyG901 Oct 11, 2024

LillyG901 Oct 11, 2024

madbkr commented Oct 11, 2024

LillyG901 commented Oct 11, 2024


		short-description

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

Update CONTRIBUTING and README #1808 #1937

Update CONTRIBUTING and README #1808 #1937

Conversation

madbkr commented Oct 2, 2024 • edited by stap-m Loading

Summary of the discussion

Type of change (CHANGELOG.md)

Update

Workflow checklist

Automation

PR-Assignee

Reviewer

stap-m left a comment

Choose a reason for hiding this comment

stap-m commented Oct 7, 2024

ColinHDev left a comment

Choose a reason for hiding this comment

LillyG901 left a comment

Choose a reason for hiding this comment

LillyG901 Oct 11, 2024

Choose a reason for hiding this comment

LillyG901 Oct 11, 2024

Choose a reason for hiding this comment

LillyG901 Oct 11, 2024

Choose a reason for hiding this comment

LillyG901 Oct 11, 2024

Choose a reason for hiding this comment

LillyG901 Oct 11, 2024

Choose a reason for hiding this comment

LillyG901 Oct 11, 2024

Choose a reason for hiding this comment

LillyG901 Oct 11, 2024

Choose a reason for hiding this comment

madbkr commented Oct 11, 2024

LillyG901 commented Oct 11, 2024

madbkr commented Oct 2, 2024 •

edited by stap-m

Loading