Skip to content

Latest commit

 

History

History
177 lines (119 loc) · 5.28 KB

CONTRIBUTING.md

File metadata and controls

177 lines (119 loc) · 5.28 KB
Raw

Contributing to Collaborative Development

Prerequisites

Types of interaction

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.

B. Comment

You can provide ideas, hints or report bugs in issues, in PR, at meetings or other channels. This is no development but can be considered a notable contribution. If you wish, add your name and details to CITATION.cff.

C. Contribute and Review

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

You contribute and take care of the repository. You review and answer questions.

Workflow

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.

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

Permanent branches
  • production - includes the current stable version

Creating a new (local) branch

Create a new feature branch:

git checkout -b feature-my-feature

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

On your first commit to the repo:

  • Add your name and details to CITATION.cff

Check branch status:

git status

Commit your changes

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

git add filename.md

Then commit regularly with:

git commit filename.md

Write a good commit message:

  • "If applied, this commit will ..."
  • 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

Fix your latest commit message

Do you want to improve your latest commit message?
Is your latest commit not pushed yet?
Edit the commit message of your latest commit:

git commit --amend

Push your commits

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

git push --set-upstream origin feature-my-feature

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

git push

Submit a pull request (PR)

Only if you want others to review a larger set of changes you made, create a pull request.
The PR title describes the problem you have solved.
Fill the PR template:

  • Summary of the discussion
  • Type of change

Add close #issueNumber to automatically close the corresponding issue.
Assign a Reviewer or GitHub team.
Assign yourself as Assignee
Add suitable GitHub Labels
Link the corresponding issue in Development
Create the PR

Let someone else review your PR

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

Merge the PR

Merging in this repository should not privode any problems. If anything out of the ordinary occurs, follow the GitHub guide merging a pull request.

Delete the feature branch

After merging you can delete the feature branch. If truly necessary git allows reconstruction of deleted branches.

Close the issue

Check that all steps have taken place:

  • Issue title describes the problem you solved
  • The branch was deleted
  • PR is closed
  • Issue is closed