segatools/CONTRIBUTING.md

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.
2. 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
   2. Provide additional information or things that are missing. Upload your log files, screenshots, videos etc. Be careful and remove sensitive information
   3. Give a thumbs up to the issue to show you are interested/affected as well
3. If no existing issue is avilable, create a new one
4. Come up with a descriptive title
5. USE OUR BUG REPORTING TEMPLATE: Pick it by selecting Bug on the Description section
6. 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
7. 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 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 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"
2. Fork the upstream repository (Fork button on the top right on the main page of the repository)
3. You can start editing files like documentation easily inside gitlab which might be the prefered option for many non-coders
4. Clone your fork to your local machine and start working on stuff
5. Ensure you push your changes to your fork on gitlab
6. When done, go to the Merge Requests section on the left sidebar of the upstream repository
7. Hit the New merge request button
8. Select the master branch as the source branch
9. Select whatever branch you worked, likely master if you didn't change that, as the target branch
10. Hit Compare branches and continue
11. Provide a descriptive title of what your change is about
12. USE OUR MR TEMPLATES
    1. If you submit a bugfix, use the Bugfix tempalte and fill in the sections
    2. If you submit a new feature, use the Feature template and fill in the sections
13. 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
14. If any of your changes are tied to one or multiple issues, link them in the description
15. 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.