|
| 1 | +# Contributing to Eclipse Thingweb |
| 2 | + |
| 3 | +Thanks for your interest in this project. General information |
| 4 | +regarding source code management, builds, coding standards, and |
| 5 | +more can be found here: |
| 6 | + |
| 7 | +* https://projects.eclipse.org/projects/iot.thingweb/developer |
| 8 | + |
| 9 | +## Legal Requirements |
| 10 | + |
| 11 | +Thingweb is an [Eclipse IoT](https://iot.eclipse.org) project and as such is governed by the Eclipse Development process. |
| 12 | +This process helps us in creating great open source software within a safe legal framework. |
| 13 | + |
| 14 | +Thus, 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) and follow these preliminary steps: |
| 15 | + |
| 16 | +* Obtain an [Eclipse Foundation account](https://accounts.eclipse.org/) |
| 17 | + * Anyone who currently uses Eclipse Bugzilla or Gerrit systems already has one of those |
| 18 | + * Newcomers can [create a new account](https://accounts.eclipse.org/user/register?destination=user) |
| 19 | +* Add your GiHub username to your Eclipse Foundation account |
| 20 | + * ([Log into Eclipse](https://accounts.eclipse.org/)) |
| 21 | + * Go to the *Edit Profile* tab |
| 22 | + * Fill in the *GitHub ID* under *Social Media Links* and save |
| 23 | +* Sign the [Eclipse Contributor Agreement](http://www.eclipse.org/legal/ECA.php) |
| 24 | + * ([Log into Eclipse](https://accounts.eclipse.org/)) |
| 25 | + * If the *Status* entry *Eclipse Contributor Agreement* has a green checkmark, the ECA is already signed |
| 26 | + * If not, go to the *Eclipse Contributor Agreement* tab or follow the corresponding link under *Status* |
| 27 | + * Fill out the form and sign it electronically |
| 28 | +* Sign-off every commit using the same email address used for your Eclipse account |
| 29 | + * Set the Git user email address with `git config user.email "<your Eclipse account email>"` |
| 30 | + * Add the `-s` flag when you make the commit(s), e.g. `git commit -s -m "feat: add support for magic"` |
| 31 | +* Open a [Pull Request](https://github.com/eclipse-thingweb/node-wot/pulls) |
| 32 | + |
| 33 | +For more information, please see the Eclipse Committer Handbook: |
| 34 | +https://www.eclipse.org/projects/handbook/#resources-commit |
| 35 | + |
| 36 | +## Commits |
| 37 | + |
| 38 | +Eclipse Thingweb uses Conventional Changelog, which structure Git commit messages in a way that allows automatic generation of changelogs. |
| 39 | +Commit messages must be structured as follows: |
| 40 | +``` |
| 41 | +<type>(<scope>): <subject> |
| 42 | +<BLANK LINE> |
| 43 | +<body> |
| 44 | +<BLANK LINE> |
| 45 | +<footer> |
| 46 | +``` |
| 47 | + |
| 48 | +* `<type>`: A noun specifying the type of change, followed by a colon and a space. The types allowed are: |
| 49 | + * `feat`: A new feature |
| 50 | + * `fix`: A bug fix |
| 51 | + * `refactor`: Code change that neither fixes a bug or adds a feature (not relevant for end user) |
| 52 | + * `perf`: Change improves performance |
| 53 | + * `style`: Change does not affect the code (e.g., formatting, whitespaces) |
| 54 | + * `test`: Adding missing tests |
| 55 | + * `chore`: Change of build process or auxiliary tools |
| 56 | + * `docs`: Documentation only changes |
| 57 | +* `<scope>`: Optional. A term of free choice specifying the place of the commit change, enclosed in parentheses. Examples: |
| 58 | + * `feat(binding-coap): ...` |
| 59 | + * `fix(cli): ...` |
| 60 | + * `docs: ...` (no scope, as it is optional) |
| 61 | +* `<subject>`: A succinct description of the change, e.g., `add support for magic` |
| 62 | + * Use the imperative, present tense: "add", not "added" nor "adds" |
| 63 | + * Do not capitalize first letter: "add", not "Add" |
| 64 | + * No dot (.) at the end |
| 65 | +* `<body>`: Optional. Can include the motivation for the change and contrast this with previous behavior. |
| 66 | + * Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes" |
| 67 | +* `<footer>`: Optional. Can be used to automatically close GitHub Issues and to document breaking changes. |
| 68 | + * The prefix `BREAKING CHANGE: ` idicates API breakage (corresponding to a major version change) and everything after is a description what changed and what needs to be done to migrate |
| 69 | + * GitHub Issue controls such as `Fixes #123` or `Closes #4711` must come before a potential `BREAKING CHANGE: `. |
| 70 | + |
| 71 | +Examples: |
| 72 | +``` |
| 73 | +docs: improve how to contribute |
| 74 | +``` |
| 75 | +``` |
| 76 | +feat(core): add support for magic |
| 77 | +
|
| 78 | +Closes #110 |
| 79 | +``` |
| 80 | +``` |
| 81 | +feat(core): add support for magic |
| 82 | +
|
| 83 | +Simplify the API by reducing the number of functions. |
| 84 | +
|
| 85 | +Closes #110 |
| 86 | +BREAKING CHANGE: Change all calls to the API to the new `do()` function. |
| 87 | +``` |
| 88 | + |
| 89 | +## Pull Requests and Feature Branches |
| 90 | + |
| 91 | +* Do not merge with master while developing a new feature or providing a fix in a new branch |
| 92 | +* Do a rebase if updates in the master such as a fix are required: |
| 93 | +``` |
| 94 | +git checkout master && git pull && git checkout - && git rebase master |
| 95 | +``` |
| 96 | +* Pull Requests are merged using rebase |
| 97 | + |
| 98 | +## Contact |
| 99 | + |
| 100 | +Contact the project developers via the project's "dev" list. |
| 101 | + |
| 102 | +* https://dev.eclipse.org/mailman/listinfo/thingweb-dev |
0 commit comments