Merge pull request #21 from t4d-gmbh/7-contributing-to-opensource-pro…

…jects

Contributing to open source projects

source/content/contributing/index.md

@@ -1,15 +1,30 @@
-# Contributing to 🔓 open source projects
+# Contributing to 🔓 Open Source Repositories
+
+{% if page %}
+When using software — whether open source or proprietary — we often have ideas or opinions on how to improve it.
+We might find certain aspects of the software or its documentation unclear, or we may spot typos and minor issues that we could easily fix ourselves.
+
+Today is your lucky day!
+You will learn just how simple it is to contribute to publicly hosted repositories on remote services like <i class="fab fa-github"></i> **GitHub** and <i class="fab fa-gitlab"></i> **GitLab**, so that next time when you stumble across some bug in some open-source project you actually can suggest your own fix.
+{% endif %}
+&nbsp;
+```{epigraph}
+In most cases external contributions follow a general workflow.
+
+However, be sure to always consult the contribution guidelines of an open source <i class="fab fa-git"></i> repository.
+```
+
 {% if slide %}
 <!-- BUILDING THE SLIDES -->
 ```{toctree}
 :maxdepth: 2
 
-./github_howto
+./step_by_step
 
 ```
 {% else %}
 <!-- BUILDING THE PAGES -->
 <!-- build the page content here -->
-```{include} ./github_howto.md
+```{include} ./step_by_step.md
 ```
 {% endif %}

source/content/contributing/step_by_step.md

@@ -0,0 +1,58 @@
+## Step-by-Step
+
+{% if page %}##### {% endif %}1. **Check Existing Issues** 👀{% if slide %} Check both {octicon}`issue-opened;0.8em` open and {octicon}`issue-closed;0.8em` closed Issues
+{% else %} 
+   - Browse existing Issues - {octicon}`issue-opened;0.8em` open and {octicon}`issue-closed;0.8em` closed ones - to see if the same or a similar Issue was already created.
+   - If your Issue exists already, check for related Merge/Pull Requests and if they implement what you had in mind.
+     If not, scip the next step (i.e. don't create a new {octicon}`issue-opened;0.8em` Issue) and simply proceed with step 3. **Read Documentation**.
+{% endif %}
+
+{% if page %}##### {% endif %}2. **Open an {octicon}`issue-opened;0.8em` Issues** 📝{% if slide %} Explain why some work needs to be done.
+{% else %} 
+   - Write a short and concise description of the Bug, Question, or Suggestion.
+   - Focus on defining the Issue such that it becomes clear **why some work should be done**.
+{% endif %}
+
+{% if page %}##### {% endif %}3. **Read Documentation** 📚{% if slide %} Consult `CONTRIBUTING` and `README.md`.
+{% else %}
+   - Check for guidelines on how to contribute.
+     Usually, they are to be found in a file called `CONTRIBUTING` or in the `README.md`.
+   - If unsure, simply stick to this step-by-step workflow
+{% endif %}
+
+{% if page %}##### {% endif %}4. **Fork the Repository** 🍴{% if slide %} Create a personal copy of the repository.
+{% else %}
+   - Create a personal copy of the repository by forking it.
+{% endif %}
+
+{% if page %}##### {% endif %}5. **Make Changes** ✏️{% if slide %} Implement in the forked repo. following best practices.
+{% else %}
+   - Implement the changes or features you want to contribute.
+     For smaller changes you might directly work on the healthy reference (i.e. **`main`**) of the forked repository.
+     Bigger changes should be implemented in a separate branch following the feature branch approach, for example.
+   - Follow the project's coding style and guidelines.
+   - Make sure the branch you implement the changes in remains up to date with the target branch from to repository.
+   - Test and document your changes.
+{% endif %}
+
+{% if page %}##### {% endif %}6. **Create a Merge/Pull Request** 🔄{% if slide %} Link it to the related Issue.
+{% else %}
+   - Go to the original repository and submit a Merge/Pull Request to propose your changes.
+   - Follow the guidelines, if present. If not:
+     - Link the related issue with a closing statement (e.g. `Closes #123`)
+     - Short description of how you addressed the Issue in your changes.
+     - Explain why you followed a particular approach (if unclear).
+{% endif %}
+
+{% if page %}#### {% endif %}7. **Participate in Code Review** 👥{% if slide %} Be open for feedback and repsect the maintainers decisions.
+{% else %}
+   - Engage with project maintainers and other contributors during the review process.
+   - Be open to feedback and make any necessary revisions.
+   - Respect the maintainers decisions and adaptations, if you are not happy with them you can alwasy keep your forked repository and maintain it on your own!
+{% endif %}
+
+{% if page %}#### {% endif %}8. 🌟 **Stay Engaged** 🌟{% if slide %}
+{% else %}
+   - Once the Merge/Pull Request is merged or closed, feel free to delete your fork of the repository again.
+   - Continue to contribute to the project by helping with other issues or discussions.
+{% endif %}

source/content/index.md

@@ -7,5 +7,6 @@ popular_remotes/index
 remote_service_features/index
 project_management/index
 organizing_and_more/index
+contributing/index
 exercise/index
 ```