mirror of
https://github.com/openSUSE/osem.git
synced 2026-08-13 19:54:02 +00:00
Bring back some of the contribution guidelines
We had a couple of create issue->immediately send PR submissions again. Let's explain a bit more what we expect from people.
This commit is contained in:
parent
ce79c1ffd4
commit
c4d7e7f4bf
1 changed files with 62 additions and 9 deletions
|
|
@ -1,4 +1,5 @@
|
||||||
# Contributing to OSEM
|
# Contributing to OSEM
|
||||||
|
|
||||||
We here at OSEM are open for all types of contributions from anyone. Tell us about our [issues/ideas](https://github.com/openSUSE/osem/issues/new), propose code changes via [pull requests](https://help.github.com/articles/using-pull-requests) or contribute artwork and documentation.
|
We here at OSEM are open for all types of contributions from anyone. Tell us about our [issues/ideas](https://github.com/openSUSE/osem/issues/new), propose code changes via [pull requests](https://help.github.com/articles/using-pull-requests) or contribute artwork and documentation.
|
||||||
|
|
||||||
We welcome all new developers and are also prepared to mentor you through your first contributions! All OSEM maintainers are seasoned developers and have participated in mentoring programs, such as [GSoC](https://summerofcode.withgoogle.com/) and [RGSoC](https://railsgirlssummerofcode.org/).
|
We welcome all new developers and are also prepared to mentor you through your first contributions! All OSEM maintainers are seasoned developers and have participated in mentoring programs, such as [GSoC](https://summerofcode.withgoogle.com/) and [RGSoC](https://railsgirlssummerofcode.org/).
|
||||||
|
|
@ -13,6 +14,7 @@ We need your input and contributions to OSEM. In particular we seek the followin
|
||||||
Read this guide on how to do that.
|
Read this guide on how to do that.
|
||||||
|
|
||||||
## How to contribute code
|
## How to contribute code
|
||||||
|
|
||||||
1. Fork the repository and make a pull-request with your changes
|
1. Fork the repository and make a pull-request with your changes
|
||||||
1. Make sure that the test suite passes and that you comply to our code style
|
1. Make sure that the test suite passes and that you comply to our code style
|
||||||
1. Please increase code coverage with your pull request
|
1. Please increase code coverage with your pull request
|
||||||
|
|
@ -20,10 +22,59 @@ Read this guide on how to do that.
|
||||||
1. If you are already a contributor and you get a positive review, you can merge your pull-request yourself
|
1. If you are already a contributor and you get a positive review, you can merge your pull-request yourself
|
||||||
1. If you are not already a contributor, one of the existing contributors will merge your pull-request
|
1. If you are not already a contributor, one of the existing contributors will merge your pull-request
|
||||||
|
|
||||||
|
**However, please bear in mind the following things:**
|
||||||
|
|
||||||
|
### Discuss Large Changes in Advance
|
||||||
|
|
||||||
|
If you see a glaring flaw within OSEM, resist the urge to jump into the
|
||||||
|
code and make sweeping changes right away. We know it can be tempting, but
|
||||||
|
especially for large, structural changes it's a wiser choice to first discuss
|
||||||
|
them in the [issue list](https://github.com/openSUSE/osem/issues).
|
||||||
|
|
||||||
|
A good rule of thumb, of what a *structural change* is, is to estimate how much
|
||||||
|
time would be wasted if the pull request was rejected. If it's a couple of minutes
|
||||||
|
then you can probably dive head first and eat the loss in the worst case. Otherwise,
|
||||||
|
making a quick check with the other developers could save you lots of time down the line.
|
||||||
|
|
||||||
|
Why? It may turn out that someone is already working on this or that someone already
|
||||||
|
has tried to solve this and hit a roadblock, maybe there even is a good reason
|
||||||
|
why this particular flaw exists? If nothing else, a discussion of the change will
|
||||||
|
usually familiarize the reviewer with your proposed changes and streamline the
|
||||||
|
review process when you finally create a pull request.
|
||||||
|
|
||||||
|
### Small Commits & Pull Request Scope
|
||||||
|
|
||||||
|
A commit should contain a single logical change, the scope should be as small
|
||||||
|
as possible. And a pull request should only consist of the commits that you
|
||||||
|
need for your change. If it's possible for you to split larger changes into
|
||||||
|
smaller blocks please do so.
|
||||||
|
|
||||||
|
Why? Limiting the scope of commits/pull requests makes reviewing much easier.
|
||||||
|
Because it will usually mean each commit can be evaluated independently and a
|
||||||
|
smaller amount of commits per pull request usually also means a smaller amount
|
||||||
|
of code to be reviewed.
|
||||||
|
|
||||||
|
### Proper Commit Messages
|
||||||
|
|
||||||
|
We are keen on proper commit messages because they will help us to maintain
|
||||||
|
this code in the future. We define proper commit messages like this:
|
||||||
|
|
||||||
|
* The title of your commit message summarizes **what** has been done
|
||||||
|
* The body of your commit message explains **why** you have done this
|
||||||
|
|
||||||
|
If the title is to small to explain **what** you have done, then you can of course
|
||||||
|
elaborate about it in the body. Please avoid explaining *how* you have done this,
|
||||||
|
we are developers too and we see the diff, if we do not understand something we will
|
||||||
|
ask you in the review.
|
||||||
|
|
||||||
|
Additional to **what** and **why** you should explain potential **side-effects** of
|
||||||
|
this change, if you are aware of any.
|
||||||
|
|
||||||
|
The content is most important, but please also use a [proper style](https://github.com/openSUSE/osem/wiki/Commit-message-guidelines).
|
||||||
|
|
||||||
## Development Environment
|
## Development Environment
|
||||||
|
|
||||||
### with docker-compose
|
To isolate your host system from OSEM development we have prepared a container
|
||||||
To isolate you host system from OSEM development we have prepared a container
|
|
||||||
based development environment, based on [docker](https://www.docker.com/) and
|
based development environment, based on [docker](https://www.docker.com/) and
|
||||||
[docker-compose](https://docs.docker.com/compose/). Here's a step by step guide
|
[docker-compose](https://docs.docker.com/compose/). Here's a step by step guide
|
||||||
how to set it up.
|
how to set it up.
|
||||||
|
|
@ -66,23 +117,25 @@ sed "s/13042/`id -u`/" docker-compose.override.yml.example > docker-compose.over
|
||||||
docker-compose exec osem /bin/bash -l
|
docker-compose exec osem /bin/bash -l
|
||||||
```
|
```
|
||||||
|
|
||||||
|
1. Want to know more?
|
||||||
|
In our wiki you can find more information about what is possible in our development environment,
|
||||||
|
how we work with each other on github or other topics of interest for OSEM developers.
|
||||||
|
|
||||||
|
https://github.com/openSUSE/osem/wiki
|
||||||
|
|
||||||
## How to contribute translations
|
## How to contribute translations
|
||||||
|
|
||||||
Please refer to our [translation guide](https://github.com/openSUSE/osem/wiki/Translation) in the wiki.
|
Please refer to our [translation guide](https://github.com/openSUSE/osem/wiki/Translation) in the wiki.
|
||||||
|
|
||||||
## Want to know more?
|
|
||||||
In our wiki you can find more information about what is possible in our development environment,
|
|
||||||
how we work with each other on github or other topics of interest for developers. Visit us at
|
|
||||||
>>>>>>> Introduces docker-compose to the contribution guide
|
|
||||||
|
|
||||||
https://github.com/openSUSE/osem/wiki
|
|
||||||
|
|
||||||
## Code of Conduct
|
## Code of Conduct
|
||||||
|
|
||||||
OSEM is part of the openSUSE project. We follow all the
|
OSEM is part of the openSUSE project. We follow all the
|
||||||
[openSUSE Guiding Principles!](http://en.opensuse.org/openSUSE:Guiding_principles)
|
[openSUSE Guiding Principles!](http://en.opensuse.org/openSUSE:Guiding_principles)
|
||||||
If you think someone doesn't do that, please let us know at maintainers@osem.io or
|
If you think someone doesn't do that, please let us know at maintainers@osem.io or
|
||||||
address your concerns to the [openSUSE Board](https://en.opensuse.org/openSUSE:Board).
|
address your concerns to the [openSUSE Board](https://en.opensuse.org/openSUSE:Board).
|
||||||
|
|
||||||
## Contact
|
## Contact
|
||||||
|
|
||||||
GitHub issues and pull requests are the primary way for communicating about specific proposed
|
GitHub issues and pull requests are the primary way for communicating about specific proposed
|
||||||
changes to this project. If you have other questions feel free to subscribe to
|
changes to this project. If you have other questions feel free to subscribe to
|
||||||
the [opensuse-web@opensuse.org](http://lists.opensuse.org/opensuse-web/)
|
the [opensuse-web@opensuse.org](http://lists.opensuse.org/opensuse-web/)
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue