Skip to content

Commit

Permalink
Merge branch 'production' into feauture-227
Browse files Browse the repository at this point in the history
  • Loading branch information
@christian-rli
christian-rli committed Jul 4, 2024
2 parents f592667 + 2d8bd3d commit f9790f9
Show file tree
Hide file tree
Showing 29 changed files with 432 additions and 406 deletions.
36 changes: 36 additions & 0 deletions CITATION.cff
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
cff-version: 1.2.0
message: If you use this software, please cite it was below.
authors:
- name: Hannah Förster
alias: @han-f
affiliation: Öko-Institut e.V
- name: Lukas Emele
alias: @l-emele
affiliation: Öko-Institut e.V
- name: Christian Hofmann
alias: @christian-rli
affiliation: Reiner Lemoine Institut
- name: Jonas Huber
alias: @jh-RLI
affiliation: Reiner Lemoine Institut
- name: Ludwig Hülk
alias: "@Ludee"
affiliation: "Öko-Institut e.V"
orcid: https://orcid.org/0000-0003-4655-2321
- name: Vismaya Jochem
alias: @vismayajochem
affiliation: Reiner Lemoine Institut
- name: Adel Memariani
alias: @adelmemariani
affiliation: OvGU
- name: Mirjam Stappel
alias: @stap-m
affiliation: OvGU
- name: Christian Winger
alias: @wingechr
affiliation: Öko-Institut e.V
title: "Open Energy Academy"
license: AGPL-3.0
url: "https://github.com/OpenEnergyPlatform/academy"
citation:
- text: "Förster et al. (2024). Open Energy Academy. https://openenergyplatform.github.io/academy"
162 changes: 46 additions & 116 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,13 @@ Version: super-repo v0.1.0

## Types of interaction

This repository is following the [Contributor Covenant Code of Conduct](https://github.com/OpenEnergyPlatform/academy/blob/main/CODE_OF_CONDUCT.md). <br>
Please be self-reflective and always maintain a good culture of discussion and active participation.

### A. Use

Since the open license allows free use, no notification is required.
However, for the authors it is valuable information who uses the software for what purpose.
Indicators are `Watch`, `Fork` and `Starred` of the repository.
If you are a user, please add your name and details in USERS.cff

### B. Comment

Expand All @@ -34,92 +32,45 @@ If you wish, add your name and details to `CITATION.cff`.

### C. Contribute and Review

You add code and become an author of the repository.
You have to follow the workflow!
Add code or text and become an author of the repository.
Please follow the workflow!
If you are a contributor to this repository, please add your name and details in USERS.cff

### D. Maintain and Release
### D. Maintain

You contribute and take care of the repository.
You review and answer questions.
You coordinate and carry out the release.

## Workflow

The workflow for contributing to this project was inspired by the workflow described by [Vincent Driessen](https://nvie.com/posts/a-successful-git-branching-model/).
The intention of this repository is to provide a reasonably quick interface to
make changes to the documentation pages called Open Energy Academy. Therefore,
our commonly used git workflow does not apply here. You are allowed to make
changes directly in the production branch und push them to appear on the live
website. You may fix small typos directly leaving a summary in your commit
message. For anything larger, please write an issue using the issue template.
You can either solve that issue yourself and reference it in your commit
message or assign someone else to the issue.

### 1. Describe the issue on GitHub

Create [an issue](https://help.github.com/en/articles/creating-an-issue)
in the GitHub repository.
The `issue title` describes the problem you will address. <br>
This is an important step as it forces one to think about the "issue".
Make a checklist for all needed steps if possible.

### 2. Solve the issue locally

#### 2.0. Get the latest version of the `develop` branch

Load the `develop branch`:

```bash
git checkout develop
```

Update with the latest version:

```bash
git pull
```
You are welcome to open a new branch and work on larger topics before
publishing them.

##### Permanent branches

- production - includes the current stable version
- gh-pages - Contains the compiled documentation

#### 2.1. Create a new (local) branch
#### Creating a new (local) branch

Create a new feature branch:

```bash
git checkout -b feature-1314-my-feature
git checkout -b feature-my-feature
```

Naming convention for branches: `type`-`issue-nr`-`short-description`

##### `type`

- feature - includes the feature that will be implemented
- hotfix - includes small improvements before an release, should be branched from a release branch
- release - includes the current version to be released

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

##### `issue-nr`
Naming convention for branches: `type`-`short-description`
Examples of branch names: `feature-add-new-ontology-class`

The `issueNumber` should be taken from Step 1. Do not use the "#".

##### `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)
- Avoid using capital letters
- Do not put your name to the branch name, it's a collaborative project
- Branch names should be precise and informative

Examples of branch names: `feature-42-add-new-ontology-class`, `feature-911-branch-naming-convention`, `hotfix-404-update-api`, `release-v0.10.0`

#### 2.2. Start editing the files

- Divide your feature into small logical units
- Start to write the documentation or a docstring
- Don't rush, have the commit messages in mind
- Add your changes to the CHANGELOG.md

On first commit to the repo:
On your first commit to the repo:

- Add your name and details to CITATION.cff

Expand All @@ -129,7 +80,7 @@ Check branch status:
git status
```

#### 2.3. Commit your changes
#### Commit your changes

If the file does not exist on the remote server yet, use:

Expand All @@ -146,16 +97,15 @@ git commit filename.md
Write a good `commit message`:

- "If applied, this commit will ..."
- Follow [existing conventions for commit messages](https://chris.beams.io/posts/git-commit)
- Keep the subject line [shorter than 50 characters](https://chris.beams.io/posts/git-commit/#limit-50)
- Do not commit more than a few changes at the time: [atomic commits](https://en.wikipedia.org/wiki/Atomic_commit)
- Use [imperative](https://chris.beams.io/posts/git-commit/#imperative)
- Do not end the commit message with a [period](https://chris.beams.io/posts/git-commit/#end) ~~.~~
- Allways end the commit message with the `issueNumber` including the "#"
- Keep the subject line shorter than 50 characters
- Do not commit more than a few changes at the time
- Use imperative
- Do not end the commit message with a period
- Always end the commit message with the `issueNumber` including the "#"

Examples of commit message: `Added function with some method #42` or `Update documentation for commit messages #1`

#### 2.4 Fix your latest commit message
#### Fix your latest commit message

Do you want to improve your latest commit message? <br>
Is your latest commit not pushed yet? <br>
Expand All @@ -165,83 +115,63 @@ Edit the commit message of your latest commit:
git commit --amend
```

### 3. Push your commits
### Push your commits

Push your `local` branch on the remote server `origin`. <br>
If your branch does not exist on the remote server yet, use:

```bash
git push --set-upstream origin feature-1314-my-feature
git push --set-upstream origin feature-my-feature
```

Then push regularly with:
When pushing directly to production or after having gone through the previous
step, push regularly with:

```bash
git push
```

### 4. Submit a pull request (PR)
### Submit a pull request (PR)

Follow the GitHub guide [creating-a-pull-request](https://help.github.com/en/articles/creating-a-pull-request). <br>
The PR should be directed: `base: develop` <- `compare: feature-1-collaboration`. <br>
Only if you want others to review a larger set of changes you made, create a pull request. <br>
The `PR title` describes the problem you have solved. <br>
Fill the PR template:

- Summary of the discussion
- Type of change (CHANGELOG.md)
- Workflow checklist
- Type of change

Add `close #issueNumber` to [automatically close](https://help.github.com/en/github/managing-your-work-on-github/closing-issues-using-keywords) the corresponding issue. <br>
Assign a `Reviewer` or GitHub team. <br>
Assign yourself as `Assignee` <br>
Add suitable GitHub `Labels` <br>
Link the corresponding issue in `Development` <br>
`Create draft pull request` <br>

#### 4.1. Update the Changelog

Update comment of PR with `#PullRequestNumber` <br>
Add to the corresponding sections in `CHANGELOG.md` <br>
Commit and push changelog <br>

#### 4.2. Update the Documentation

Update the documentation <br>
Commit and push documentation <br>

#### 4.3. Convert draft to Pull Request

Check `Ready for review`
Create the PR

#### 4.4. Let someone else review your PR
#### Let someone else review your PR

Follow the GitHub guide [approving a pull request with required reviews](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews). <br>
Assign one reviewer or a user group and get into contact.

If you are the reviewer:

- Check the changes in all corresponding files.
- Checkout the branch and run code.
- Checkout the branch and if applicable, run code.
- Comment if you would like to change something (Use `Request changes`)
- If all tests pass and all changes are good, `Approve` the PR.
- Leave a comment and some nice words!

#### 4.1. Merge the PR
#### Merge the PR

Follow the GitHub guide [merging a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request).
Merging in this repository should not privode any problems. If anything out of the ordinary occurs, follow the GitHub guide [merging a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request).

#### 4.2. Delete the feature branch
#### Delete the feature branch

Follow the GitHub guide [deleting a branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository#deleting-a-branch).
After merging you can delete the feature branch. If truly necessary git allows reconstruction of deleted branches.

### 5. Close the issue
### Close the issue

Document the result in a few sentences and close the issue. <br>
Check that all steps have been documented:
Check that all steps have taken place:

- Issue title describes the problem you solved?
- All commit messages are linked in the issue?
- The branch was deleted?
- Entry in CHANGELOG.md?
- PR is closed?
- Issue is closed?
- Issue title describes the problem you solved
- The branch was deleted
- PR is closed
- Issue is closed
31 changes: 31 additions & 0 deletions USERS.cff
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
cff-version: 1.2.0
message: "If you use contributed to this software, please leave your name for reference.
authors:
- name: Hannah Förster
alias: @han-f
affiliation: Öko-Institut e.V
- name: Lukas Emele
alias: @l-emele
affiliation: Öko-Institut e.V
- name: Christian Hofmann
alias: @christian-rli
affiliation: Reiner Lemoine Institut
- name: Jonas Huber
alias: @jh-RLI
affiliation: Reiner Lemoine Institut
- name: Ludwig Hülk
alias: "@Ludee"
affiliation: "Öko-Institut e.V"
orcid: https://orcid.org/0000-0003-4655-2321
- name: Vismaya Jochem
alias: @vismayajochem
affiliation: Reiner Lemoine Institut
- name: Adel Memariani
alias: @adelmemariani
affiliation: OvGU
- name: Mirjam Stappel
alias: @stap-m
affiliation: OvGU
- name: Christian Winger
alias: @wingechr
affiliation: Öko-Institut e.V
9 changes: 7 additions & 2 deletions docs/courses/01_introduction.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,12 @@
# 01 - Introduction

Welcome to the courses section of the Open Energy Academy (OEA). On the OEA, we have created a series of training courses which provide various material on how to interact with OEP. Each of our training courses provides targeted content directly within the course and / or links to learning materials which cater to different levels of expertise. Some materials are targeted at fluent programmers, others are targeted at persons who prefer to interact with the OEP visually.
As a visual guide regarding what to expect behind links you may find in a training couse, we use the following icons:
Welcome to the courses section of the Open Energy Academy (OEA). On the OEA, we have created a series of training courses which provide various material on how to interact with [Open Energy Platform](https://openenergyplatform.org) (OEP).
The OEP is a web-interface for things related research data management in climate and energy systems modelling. On the OEP, researchers can publish data including FAIR metadata (which meet principles of findability, accessibility, interoperability, and reusability) and thus contribute to increasing transparency and interoperability of their research. The functionalities the OEP offers help deliver the [research data management lifecycle](https://liascript.github.io/course/?https://raw.githubusercontent.com/NFDI4Energy/EFZN_rdm/main/README.md#3).

To get familiar with research data management in general, we recommend to visit this interactive and comprehensive course [Research Data Management](https://liascript.github.io/course/?https://raw.githubusercontent.com/NFDI4Energy/EFZN_rdm/main/README.md#1) by University of Oldenburg, Center for Lifelong Learning, Digitalisierte Energiesysteme, funded by Energie-Forschungszentrum Niedersachsen and supported by nfdi4energy and Zentrum für digitale Innovationen Niedersachsen.

Each of the training courses here on the OEA are targeted at working with the Open Energy Platform and its tools. The courses contain written content and / or links to learning materials which cater to different levels of expertise. Some materials are targeted at fluent programmers, others are targeted at persons who prefer to interact with the OEP visually.
As a visual guide regarding what to expect behind links you may find in a training course, we use the following icons:

:oep-icon-code: links to written training material. The material may include some code for guidance.

Expand Down
10 changes: 5 additions & 5 deletions docs/courses/03_download.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,30 +26,30 @@ This tutorial teaches you how to use the free text search and tags to filter for

## How can I download data?

:oep-icon-code: [Process query result data and save to file (tutorial)](../tutorials/01_api/01_api_download.ipynb):
:oep-icon-code: [Process query result data and save to file](../tutorials/01_api/01_api_download.ipynb) (tutorial):

Learn how to use the REST-full-HTTP API in Python for selecting data on the OEP, make calculations
with it and save the results to a file.

:oep-icon-text: [How to download data - CSV and data package (tutorial)](../tutorials/99_other/download.md):
:oep-icon-text: [How to download data - CSV and data package](../tutorials/99_other/download.md) (tutorial):

Learn how easy it is do download any data table you are viewing on the OEP table with only one click and why a data package makes a difference.

## How can I interact with data?

:oep-icon-code: [Data queries via API (tutorial)](../tutorials/01_api/01_api_download.ipynb):
:oep-icon-code: [Data queries via API](../tutorials/01_api/01_api_download.ipynb) (tutorial):

This tutorial provides an overview of how you can select and filter data that resides on the OEP via the REST-full-HTTP
API in Python

:oep-icon-code: [Process query result data and save to file (tutorial)](../tutorials/01_api/01_api_download.ipynb):
:oep-icon-code: [Process query result data and save to file](../tutorials/01_api/01_api_download.ipynb) (tutorial):

Learn how to use the REST-full-HTTP API in Python for selecting data on the OEP, make calculations
with it and save the results to a file.

## How can I find relevant information about scenarios on the OEP?

:oep-icon-info: Our current [scenario factsheets](https://openenergyplatform.org/factsheets/scenarios/) provide some dedicated information about specific scenarios for which projection data is available on the OEP. Please note, however, that their format was developed some time ago and they will undergo substantial updates. In the future, these scenario factsheets will be succeeded by [study factsheets (alpha)](https://openenergyplatform.org/factsheets/rdf/study/) that will hold more functionality. These improved factsheets will be based on RDF and the Open Energy Knowledge Graph (OEKG) which is currently under heavy development. Please note that this is therefore just a preview and not a fully functional feature yet.
:oep-icon-info: Our [scenario bundles](https://openenergyplatform.org/scenario-bundles/main) provide dedicated information about scenarios and their context. Context for example includes the study reports that deal with the scenario(s), the projection data available on the OEP that were created using the scenario(s), the sectors and technologies depicted and so on. These bundles are based on (Resource Description Framework) RDF and the Open Energy Knowledge Graph (OEKG) and they are tied to the [Open Energy Ontology](https://openenergyplatform.org/ontology/) (OEO) for improving comparability across scenario bundles.

---

Expand Down
8 changes: 4 additions & 4 deletions docs/courses/04_upload.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,11 @@ You can provide feedback to this course on github: [https://github.com/OpenEnerg

- want to publish their data on the OEP

:oep-icon-info: **After reading the sections of this training course you will**
:oep-icon-info: **After reading the sections of this training course you will be able to publish data**

- be able to publish data on the OEP using a visual interface - this is for those of you who do not want to program
- be able to publish data on the OEP with the REST-full-HTTP API in python - this is for those of you who want to akquire some programming skills
- be able to publish data using the oeclient or the OEP REST-API using python - this one is for those of you who can program already
- on the OEP using a visual interface - this is for those of you who do not want to program
- on the OEP with the REST-full-HTTP API in python - this is for those of you who want to akquire some programming skills
- using the oeclient or the OEP REST-API using python - this one is for those of you who can program already

## How can I publish data to the OEP without programming skills?

Expand Down
Loading

0 comments on commit f9790f9

Please sign in to comment.