93 lines
5.0 KiB
Markdown
93 lines
5.0 KiB
Markdown
# Contributing
|
|
|
|
This document outlines different types of contributions and how YOU can help us to improve the
|
|
project. Read it, as it provides guidelines that are there to help you and the maintainers.
|
|
|
|
## Reporting and discussions: Issues section on gitlab
|
|
|
|
In order to avoid information management overehad on different communication channels, discussions
|
|
we ask everyone to treat the issue section on gitlab as the place to open their relevant discussions
|
|
and bug reports regarding the project.
|
|
|
|
The maintainers of the project do not have the time nor motivation to micromanage information from
|
|
various channels. We ask *EVERYONE* to support the maintainers and developers to allow them to spend
|
|
their time on developing tasks.
|
|
|
|
## Bug reports
|
|
|
|
Follow these steps when reporting bugs to ensure you provide all information we *always* need and
|
|
make your report valuable and actionable.
|
|
|
|
1. On the segatools repository, go `Issues` on the left-hand sidebar.
|
|
1. Use the search function to check if there is an already open issue regarding what you want to
|
|
report
|
|
1. If that applies, read the open issue to check what's already covered regarding the bug
|
|
1. Provide additional information or things that are missing. Upload your log files,
|
|
screenshots, videos etc. Be careful and remove sensitive information
|
|
1. Give a thumbs up to the issue to show you are interested/affected as well
|
|
1. If no existing issue is avilable, create a new one
|
|
1. Come up with a descriptive title
|
|
1. **USE OUR BUG REPORTING TEMPLATE**: Pick it by selecting `Bug` on the `Description` section
|
|
1. Follow the sections and their instructions provided by the template and fill them in. All fields
|
|
are mandatory to provide a comprehensive report if not stated otherwise
|
|
1. When finished, submit the issue
|
|
|
|
## Git history
|
|
|
|
The project is aiming for a linear git history approach since we are convinced that it beneifts
|
|
maintenance of the project a lot in the long term.
|
|
|
|
For further details on that topic, please refer to
|
|
[the many external articles](https://dev.to/bladesensei/avoid-messy-git-history-3g26) available
|
|
about this topic by using your favorite search engine.
|
|
|
|
## Merge requests: bugfixes, new features or other code contributions
|
|
|
|
Merge requests are welcome! May it be a merge request to an already known issue or a new feature that
|
|
you consider as a valuable contribution, please open a MR.
|
|
|
|
**!!! Maintaining documentation by adding new or improving existing documentation is as important as
|
|
code !!!**
|
|
|
|
If you want to start working on a new feature that was proposed in an issue, yet, it is recommended
|
|
to reach out to the maintainers about this, first, to discuss if this contribution is valuable
|
|
to the project. Otherwise, you might waste your time on implementing something that won't make it
|
|
into master or someone else is already working on.
|
|
|
|
Please read our [development guidelines](doc/development.md) as they contain valuable information
|
|
that your contribution meets our standards. This is not meant to annoy people but ensures
|
|
consistency that the project stays maintainable for everyone.
|
|
|
|
Steps for contributing to the repository using a merge request:
|
|
|
|
1. If you are new to git, take a bit of time to learn the basics which are very simple, e.g. Google
|
|
for "git tutorial for non-programmers"
|
|
1. Fork the upstream repository (Fork button on the top right on the main page of the repository)
|
|
1. You can start editing files like documentation easily inside gitlab which might be the prefered
|
|
option for many non-coders
|
|
1. Clone your fork to your local machine and start working on stuff
|
|
1. Ensure you push your changes to your fork on gitlab
|
|
1. When done, go to the `Merge Requests` section on the left sidebar of the upstream repository
|
|
1. Hit the `New merge request` button
|
|
1. Select the `master` branch as the source branch
|
|
1. Select whatever branch you worked, likely `master` if you didn't change that, as the target
|
|
branch
|
|
1. Hit `Compare branches and continue`
|
|
1. Provide a descriptive title of what your change is about
|
|
1. **USE OUR MR TEMPLATES**
|
|
1. If you submit a bugfix, use the `Bugfix` tempalte and fill in the sections
|
|
1. If you submit a new feature, use the `Feature` template and fill in the sections
|
|
1. If you submit some minor fixes or documentation improvements, there is no template for that.
|
|
Please provide a expressive description what you did and *why* you did that
|
|
1. If any of your changes are tied to one or multiple issues, link them in the description
|
|
1. When done, hit `Submit merge request`
|
|
|
|
The maintainers will take a look at your submission and provide their feedback. The intention of
|
|
this process is to ensure the contribution meets the quality standards. Please also see this is
|
|
a learning opportunity, especially with your first contribution, if a lot of comments and change
|
|
requests are being made. The maintainers are open to discuss their suggestions/feedback if
|
|
reasonable feedback is given back to them.
|
|
|
|
Once all discussion is resolved and the involved maintainers approved your submission, it will be
|
|
merged into master and also included in the next release.
|