Update contribution guide

.gitignore

@@ -1 +1,2 @@
 public
+.project

CONTRIBUTING.md

@@ -1,64 +1,7 @@
 # Contributing to Eclipse Kuksa
 
-Thanks for your interest in this project.
+Thanks for your interest in this project!
 
-## Project description
-
-Because today's software-intensive automotive systems are still developed in
-silos by each car manufacturer or OEM in-house, long-term challenges in the
-industry are yet unresolved. Establishing a standard for car-to-cloud scenarios
-significantly improves comprehensive domain-related development activities and
-opens the market to external applications, service provider, and the use of open
-source software wherever possible without compromising security. Connectivity,
-OTA maintenance, automated driving, electric mobility, and related approaches
-increasingly demand technical innovations applicable across automotive players.
-
-* https://projects.eclipse.org/projects/iot.kuksa
-
-## Developer resources
-
-Information regarding source code management, builds, coding standards, and
-more.
-
-* https://projects.eclipse.org/projects/iot.kuksa/developer
-
-The project maintains the following source code repositories
-
-* https://github.com/eclipse/kuksa.apps
-* https://github.com/eclipse/kuksa.cloud
-* https://github.com/eclipse/kuksa.ide
-* https://github.com/eclipse/kuksa.integration
-* https://github.com/eclipse/kuksa.invehicle
-* https://github.com/eclipse/kuksa.website
-* http://git.eclipse.org/c/kuksa/kuksa.git
-* http://git.eclipse.org/c/kuksa/www.git
-
-This project uses Bugzilla to track ongoing development and issues.
-
-* Search for issues: https://eclipse.org/bugs/buglist.cgi?product=Kuksa
-* Create a new report: https://eclipse.org/bugs/enter_bug.cgi?product=Kuksa
-
-Be sure to search for existing bugs before you create another one. Remember that
-contributions are always welcome!
-
-## Eclipse Contributor Agreement
-
-Before your contribution can be accepted by the project team contributors must
-electronically sign the Eclipse Contributor Agreement (ECA).
-
-* http://www.eclipse.org/legal/ECA.php
-
-Commits that are provided by non-committers must have a Signed-off-by field in
-the footer indicating that the author is aware of the terms by which the
-contribution has been provided to the project. The non-committer must
-additionally have an Eclipse Foundation account and must have a signed Eclipse
-Contributor Agreement (ECA) on file.
-
-For more information, please see the Eclipse Committer Handbook:
-https://www.eclipse.org/projects/handbook/#resources-commit
-
-## Contact
-
-Contact the project developers via the project's "dev" list.
-
-* https://dev.eclipse.org/mailman/listinfo/kuksa-dev
+* Please find information about the project at https://www.eclipse.org/kuksa/about/
+* An overview of project resources including the code is at https://www.eclipse.org/kuksa/resources/
+* If you would like to contribute, please consult https://www.eclipse.org/kuksa/contributing/

content/contributing.md

@@ -6,7 +6,10 @@ draft: false
 
 # HowTo contribute to Eclipse Kuksa
 Great that you are interested in contributing to Eclipse Kuksa. 
-We really looking forward to receive your contribution.
+We really looking forward to receive your contribution!
+
+Get in touch! There is the [kuksa-dev mailing list](https://accounts.eclipse.org/mailing-list/kuksa-dev)
+and a weekly [Zoom meeting](https://eclipse.zoom.us/j/537310990), every Thursday 1-2pm (CET/CEST).
 
 In the project we agreed upon the following approach to add contributions to the project.
 
@@ -15,50 +18,64 @@ In the project we agreed upon the following approach to add contributions to the
 3. The new feature was at least once tested manually, deployed to a running test instance
 4. Clearly outline third party dependencies
 
-### Definition of Done
+## Definition of Done
 First, we have DoD for solved issues. Please check if you met all the items in the following list:
 
-* File headers in file OK (see section License Headers for details)
-  * EPL-2.0 license header
-  * Or, if the file is too small, configuration file: license note (see code style)
-  * Copyright and author
+* File headers in file OK (see section [License Headers](#licensing-and-file-header) for details)
+
+* Each new feature is developed in a separate branch
+  * Development branches should be named like`<github-nickname>/<issue>/<description>`, e.g. bs-jokri/#2/fix-connection-handling
+
+* Coding style
+  * Clean code is encouraged (see ‘Clean Code’ by Robert C. Martin or the 
+    [Clean Code Cheatsheet](https://www.bbv.ch/images/bbv/pdf/downloads/V2_Clean_Code_V3.pdf).
+    Reviewers might refer to specific clean code practices to help improve contributed code.
 
-* New feature is in dev branch
-  * Please use conventional branch names, which help to see who is responsible and to which issue the Pull Request corresponds
-  * Should look like`<github-nickname>/<issue>/<description>`, e.g. bs-jokri/#2/fix-connection-handling
-
 * Avoid (serious) compiler warnings
 
-* New test
-  * For new / added functionality
+* Add tests for new / added functionality
 
-* No breaking test
+* All tests pass
   * Unit testing as it is already present
   * You have more - use them!
 
 * Documentation
-  * in the Github Wiki-Section, if you have done something new
-  * At least a technical note for newly added functionality
+  * Provide the necessary technical documentation of your feature in the respective 
+    Github repository that you contribute to. Documentation is in markdown and it either 
+    included in the top-level README.md file of the Github repository, or linked from 
+    there. 
+  * Update the high-level overview of Kuksa in the [kuksa.integration Wiki at Github](https://github.com/eclipse/kuksa.integration/wiki).
+    From the wiki, provide links to relevant technical documentation in the Github repositories.
 
 * Commit style
-  * Squash your commits into one or more logical units of work. No dozens of hourly/daily commits in your pull request, please. In the ideal case, a feature is contained in one commit.
-  * Rebase onto current master so that a fast forward merge is possible, i.e. prepare merge to master.
-  * If you are not a committer to the project our commits need to be signed of with a valid Eclipse user account. Check the Eclipse handbook for details ([Eclipse Project Handbook](https://www.eclipse.org/projects/handbook/#resources-commit)).
+  * Please write brief and useful commit messages: Separate the subject from body with a blank line because the subject line
+    is shown in the git history and should summarize the commit body. Use the body to explain what and why vs. how.
+    https://chris.beams.io/posts/git-commit/#seven-rules has more tips and details.
+  * Before you push your commits to a repository, squash your commits into one or more logical units of work.
+    No dozens of hourly/daily commits in your pull request, please. In the ideal case, a feature is contained in one commit.
+    * The [Pro Git book](https://git-scm.com/book/en/v2/) has a great section on [Rewriting 
+    History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) and a section 
+    on [Squashing](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_squashing).
+  * Rebase during pull (i.e. `git pull --rebase`) instead of merging so all commits can
+    be signed off. You can also
+    [configure git to rebase by default](https://stackoverflow.com/questions/13846300/how-to-make-git-pull-use-rebase-by-default-for-all-my-repositories)
+    - you IDE will also have according configuration options. 
+  * If you are not a committer to the project your commits need to be signed off with a valid Eclipse user account. Check the Eclipse handbook for details ([Eclipse Project Handbook](https://www.eclipse.org/projects/handbook/#resources-commit)).
 
 If you checked your code according to the DoD and you feel it can be merged to master, please create a PR to master. 
 Each PR that is merged to master has to pass all tests and needs a code review of some other person of the project that looks onto your contribution from another angle, 
 i.e. didn't work with you on the new feature. Probably a good idea is to have someone from another organization doing the review.
 Maybe you already have someone in mind doing the review, then request a review from this person via the github review functionallity.
 
-### Review
+## Review
 If you conduct a code review, please look at the following issues:
 
   * Is code style ok, not really formatting, but issues like style attributes in HTML tags or exception handling useful
   * Are DoD items reached
   * Are there any design / architecture issues
   * Does the new feature fit the overall project goal, is it suitable for the community
 
-### Manual Test
+## Manual Test
 If applicable the new  feature should at least be deployed and tested by someone before actually merged to master.
 This could be done by the same person that is doing the review but could be performed  by another person.
 
@@ -73,22 +90,22 @@ and
 tested-by:email@domain.com
 ```
 
-### Third party dependencies
+## Third party dependencies
 
 If you use third party content (import / include ...), you are required to list each third party content explicitly with its version number in the documentation or your pull-request comment.
 Please note that GPL software cannot be approved for Eclipse Kuksa.
 
-### Licensing and file header
+## Licensing and file header
 
-All files contributed require headers - this will ensure the license and copyright clearing at the end. Also, all contributions must have the same license as the original source.
+All files contributed require headers - this will ensure the license and copyright clearing at the end.
+Also, all contributions must have the same license as the original source.
 
 If a file has relevant functionality add the official EPL-2.0 header as described here
 https://www.eclipse.org/legal/epl-2.0/faq.php#h.q72cnghf29k0
 
 We recommend to use the releng copyright tool at:
 https://wiki.eclipse.org/Development_Resources/How_to_Use_Eclipse_Copyright_Tool
 
-
 ```
 /*********************************************************************
 * Copyright (c) {date} {owner} [and others]
@@ -111,4 +128,20 @@ For small files such as property files, configuration files or standard XML file
 # terms and conditions of the Eclipse Distribution License v1.0 which
 # accompanies this distribution, and is available at
 # http://www.eclipse.org/org/documents/edl-v10.php
-```
+```
+
+## Eclipse Contributor Agreement
+
+Before your contribution can be accepted by the project team contributors must
+electronically sign the Eclipse Contributor Agreement (ECA).
+
+* http://www.eclipse.org/legal/ECA.php
+
+Commits that are provided by non-committers must have a Signed-off-by field in
+the footer indicating that the author is aware of the terms by which the
+contribution has been provided to the project. The non-committer must
+additionally have an Eclipse Foundation account and must have a signed Eclipse
+Contributor Agreement (ECA) on file.
+
+For more information, please see the Eclipse Committer Handbook:
+https://www.eclipse.org/projects/handbook/#resources-commit

content/resources.md

@@ -10,12 +10,22 @@ A brief documentation link collection can be found [here](https://github.com/ecl
 
 # GitHub Repositories
 
+The code is provided in the following Github repositories. Please note that
+issues are tracked and discussed in the repository of the respective sub-project. 
+
 * Eclipse Kuksa IDE: https://github.com/eclipse/kuksa.ide
+  Browser-based IDE used by developers to create applications for the Eclipse Kuksa in-vehicle 
+  platform.
 * Eclipse Kuksa Apps: https://github.com/eclipse/kuksa.apps
+  Contains applications to showcase use-cases of Eclipse Kuksa
 * Eclipse Kuksa Cloud: https://github.com/eclipse/kuksa.cloud
+  The cloud-backend of Eclipse Kuksa, including the App Store
 * Eclipse Kuksa In-Vehicle: https://github.com/eclipse/kuksa.invehicle
+  The in-vehicle platform of Eclipse Kuksa
 * Eclipse Kuksa Integration: https://github.com/eclipse/kuksa.integration
+  Integration tests for Eclipse Kuksa
 * Eclipse Kuksa Website: https://github.com/eclipse/kuksa.website
+  The sources of the Eclipse Kuksa website
 
 # Documentation
 
@@ -24,14 +34,23 @@ A brief documentation link collection can be found [here](https://github.com/ecl
 * Rover API: https://app4mc-rover.github.io/rover-app/
 * Rover Telemetry UI https://github.com/app4mc-rover/rover-telemetry-ui
 * Eclipse Kuksa Wiki: https://wiki.eclipse.org/Kuksa
+* Entry in Eclipse Foundation Project List: https://projects.eclipse.org/projects/iot.kuksa
+
+## Mailing list
+
+Contact the project developers via the project's "dev" list.
+
+* https://dev.eclipse.org/mailman/listinfo/kuksa-dev
 
 # Builds
 
-* Website Jenkins: https://jenkins.eclipse.org/kuksa/
+* Jenkins Website: https://jenkins.eclipse.org/kuksa/
 
 # APPSTACLE Deliverables and more
 
-* Available at: https://itea3.org/project/appstacle.html
+Eclipse Kuksa was created as part of the APPSTACLE project. More information
+regarding the project and the deliverables is available at
+https://itea3.org/project/appstacle.html .
 
 # Videos
 * <a href="https://www.youtube.com/watch?v=tD8pt7WMbuQ&t=3s">Automotive meets IoT: Innovating your future vehicle </a> Sebastian Schildt, Bosch