From 043f695a4aa8eefddd8c432aa16dc88c9f6adcd3 Mon Sep 17 00:00:00 2001 From: jf-cbd Date: Thu, 16 Apr 2026 18:48:53 +0200 Subject: [PATCH] Contribution guidelines proposition --- .github/issue_template.md | 41 ++++++++ .github/pull_request_template.md | 74 ++++++-------- CONTRIBUTING.md | 162 +++++++++++++++++++++---------- 3 files changed, 183 insertions(+), 94 deletions(-) create mode 100644 .github/issue_template.md diff --git a/.github/issue_template.md b/.github/issue_template.md new file mode 100644 index 0000000000..7d7406e031 --- /dev/null +++ b/.github/issue_template.md @@ -0,0 +1,41 @@ + + +## Base information + +| Question | Answer | +|-------------------------------------------|--------------------------| +| Type of issue ? | Bug report / Enhancement | +| Are you willing to create a PR for that ? | Yes / No | + +## Reproduction procedure (bug) + + + +1. On iTop x.y.z +2. With PHP x.y.z +3. First go there +4. Then do that +5. ... +6. Finally, see that... (what is expected and what is actually happening) + +Additional information (if needed) + + +## Reproduction procedure (enhancement) + + + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 4176e4b531..d15bdb853a 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,83 +1,69 @@ ## Base information -| Question | Answer -|---------------------------------------------------------------|-------- -| Related to a SourceForge thead / Another PR / Combodo ticket? | -| Type of change? | Bug fix / Enhancement / Translations - - -## Symptom (bug) / Objective (enhancement) - +| Question | Answer | +|---------------------------------------------------------------------------------|--------------------------------------| +| Related to a SourceForge thread / Another PR / A GitHub Issue / Combodo ticket? | | +| Type of change? | Bug fix / Enhancement / Translations | ## Reproduction procedure (bug) + 1. On iTop x.y.z 2. With PHP x.y.z -2. First go there -2. Then do that -3. ... -4. Finally, see that... +3. First go there +4. Then do that +5. ... +6. Finally, see that... (what is expected and what is actually happening) +Additional information (if needed) + + +## Reproduction procedure (enhancement) + + ## Cause (bug) + - ## Proposed solution (bug and enhancement) + - ## Checklist before requesting a review + + - [ ] I have performed a self-review of my code - [ ] I have tested all changes I made on an iTop instance - [ ] I have added a unit test, otherwise I have explained why I couldn't -- [ ] Is the PR clear and detailed enough so anyone can understand digging in the code? - -## Checklist of things to do before PR is ready to merge - - -- [ ] ... -- [ ] ... -- [ ] ... +- [ ] Is the PR clear and detailed enough so anyone can understand without digging in the code? \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3cb5eb8617..966c3c7f6c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,30 +4,29 @@ You want to contribute to iTop? Many thanks to you! 🎉 👍 Here are some guidelines that will help us integrate your work! - -## Contributions - ### Subjects + You are welcome to create pull requests on any of those subjects: * 🐛 bug fix * 🌐 translation / i18n / l10n -If you want to implement a **new feature**, please [create a corresponding ticket](https://sourceforge.net/p/itop/tickets/new/) for review. -If you ever want to begin implementation, do so in a fork, and add a link to the corresponding commits in the ticket. +If you want to implement a **new feature**, please [create a corresponding issue](https://github.com/Combodo/iTop/issues) for review. +We should review within two weeks, and get back to you to indicate if we're interested in your proposal or not. +f you ever want to begin implementation, do so in a fork, and add a link to the corresponding commits in the ticket. For all **security related subjects**, please see our [security policy](SECURITY.md). -All **datamodel modification** should be done in an extension. Beware that such change would -impact all existing customers, and could prevent them from -upgrading! -Combodo has a long experience of datamodel changes: they are very disruptive! +All **datamodel modification** should be done in an extension. Beware that such change would +impact all existing customers, and could prevent them from upgrading! +Combodo has a long experience of datamodel changes: they are very disruptive! This is why we avoid them in iTop core, especially the changes on existing objects/fields. -If you have an idea you're sure would benefit to all of iTop users, you may -[create a corresponding ticket](https://sourceforge.net/p/itop/tickets/new/) to submit it, but be warned that there are lots of good +If you have an idea you're sure would benefit to all of iTop users, you may +[create a corresponding ticket](https://sourceforge.net/p/itop/tickets/new/) to submit it, but be warned that there are lots of good reasons to refuse such changes. ### 📄 License and copyright + iTop is distributed under the AGPL-3.0 license (see the [license.txt] file). The iTop repository is divided in three parts: iTop (mainly PHP/JS/XML sources and dictionaries), images, and third-party libraries. @@ -37,48 +36,33 @@ Anyhow, you are encouraged to signal your contribution by the mean of `@author` If you want to use another license or keep the code ownership (copyright), you may [create an extension][wiki new ext]. [license.txt]: https://github.com/Combodo/iTop/blob/develop/license.txt -[wiki new ext]: https://www.itophub.io/wiki/page?id=latest%3Acustomization%3Astart#by_writing_your_own_extension +[wiki new ext]: https://www.itophub.io/wiki/page?id=latest%3Acustomization%3Astart#by_writing_your_own_extension ## 🔀 iTop branch model When we first start with Git, we were using the [GitFlow](https://nvie.com/posts/a-successful-git-branching-model/) branch model. As - there was some confusions about branches to use for current developed release and previous maintained release, and also because we were - using just a very few of the GitFlow commands, we decided to add just a little modification to this branch model : since april 2020 - we don't have a `master` branch anymore. +there was some confusions about branches to use for current developed release and previous maintained release, and also because we were +using just a very few of the GitFlow commands, we decided to add just a little modification to this branch model : since April 2020 +we don't have a `master` branch anymore. -Here are the branches we use and their meaning : +Here are the branches we use and their meaning : - `develop`: ongoing development version -- `release/*`: if present, that means we are working on a alpha/beta/rc version for shipping - `support/*`: maintenance branches for older versions For example, if no version is currently prepared for shipping we could have: -- `develop` containing future 3.1.0 version -- `support/3.0`: 3.0.x maintenance version -- `support/2.7`: 2.7.x maintenance version -- `support/2.6`: 2.6.x maintenance version +- `develop` containing future 3.3.0 version +- `support/3.2`: 3.2.x maintenance version -In this example, when 3.1.0-beta is shipped that will become: +And when 3.3.0 final will be out: -- `develop`: future 3.2.0 version -- `release/3.1.0`: 3.1.0-beta -- `support/3.0`: 3.0.x maintenance version -- `support/2.7`: 2.7.x maintenance version -- `support/2.6`: 2.6.x maintenance version - -And when 3.1.0 final will be out: - -- `develop`: future 3.2.0 version -- `support/3.1`: 3.1.x maintenance version (will host developments for 3.1.1) -- `support/3.0`: 3.0.x maintenance version -- `support/2.7`: 2.7.x maintenance version -- `support/2.6`: 2.6.x maintenance version +- `develop`: future 3.4.0 version +- `support/3.2`: 3.2.x maintenance version (will host developments for 3.2.4) Also note that we have a "micro-version" concept : each of those versions have a very small amount of modifications. They are made from - `support/*` branches as well. For example 2.6.2-1 and 2.6.2-2 were made from the `support/2.6.2` branch. - +`support/*` branches as well. For example 2.6.2-1 and 2.6.2-2 were made from the `support/2.6.2` branch. ## Coding @@ -92,11 +76,93 @@ A [dedicated page](https://www.itophub.io/wiki/page?id=latest%3Acustomization%3A 2. Create a branch in this fork, based on the develop branch 3. Code ! -Do create a dedicated branch for each modification you want to propose : if you don't it will be very hard to merge back your work ! +Do create a dedicated branch for each modification you want to propose : if you don't, it will be very hard to merge back your work ! -Most of the time you should based your developments on the develop branch. +Most of the time you should base your developments on the develop branch. That may be different if you want to fix a bug, please use develop anyway and ask in your PR if rebase is possible. +### 🎨 PHP styleguide# Contributing to iTop + +You want to contribute to iTop? Many thanks to you! 🎉 👍 + +Here are some guidelines that will help us integrate your work! + +### Subjects + +You are welcome to create pull requests on any of those subjects: + +* 🐛 bug fix +* 🌐 translation / i18n / l10n + +If you want to implement a **new feature**, please [create a corresponding issue](https://github.com/Combodo/iTop/issues) for review. +We should review within two weeks, and get back to you to indicate if we're interested in your proposal or not. +f you ever want to begin implementation, do so in a fork, and add a link to the corresponding commits in the ticket. + +For all **security related subjects**, please see our [security policy](SECURITY.md). + +All **datamodel modification** should be done in an extension. Beware that such change would +impact all existing customers, and could prevent them from upgrading! +Combodo has a long experience of datamodel changes: they are very disruptive! +This is why we avoid them in iTop core, especially the changes on existing objects/fields. +If you have an idea you're sure would benefit to all of iTop users, you may +[create a corresponding ticket](https://sourceforge.net/p/itop/tickets/new/) to submit it, but be warned that there are lots of good +reasons to refuse such changes. + +### 📄 License and copyright + +iTop is distributed under the AGPL-3.0 license (see the [license.txt] file). + +The iTop repository is divided in three parts: iTop (mainly PHP/JS/XML sources and dictionaries), images, and third-party libraries. +Combodo has the copyright on most of the source files in the iTop part of the repository: please do not modify the existing file copyrights. +Anyhow, you are encouraged to signal your contribution by the mean of `@author` annotations. + +If you want to use another license or keep the code ownership (copyright), you may [create an extension][wiki new ext]. + +[license.txt]: https://github.com/Combodo/iTop/blob/develop/license.txt + +[wiki new ext]: https://www.itophub.io/wiki/page?id=latest%3Acustomization%3Astart#by_writing_your_own_extension + +## 🔀 iTop branch model + +When we first start with Git, we were using the [GitFlow](https://nvie.com/posts/a-successful-git-branching-model/) branch model. As +there was some confusions about branches to use for current developed release and previous maintained release, and also because we were +using just a very few of the GitFlow commands, we decided to add just a little modification to this branch model : since April 2020 +we don't have a `master` branch anymore. + +Here are the branches we use and their meaning : + +- `develop`: ongoing development version +- `support/*`: maintenance branches for older versions + +For example, if no version is currently prepared for shipping we could have: + +- `develop` containing future 3.3.0 version +- `support/3.2`: 3.2.x maintenance version + +And when 3.3.0 final will be out: + +- `develop`: future 3.4.0 version +- `support/3.2`: 3.2.x maintenance version (will host developments for 3.2.4) + +Also note that we have a "micro-version" concept : each of those versions have a very small amount of modifications. They are made from +`support/*` branches as well. For example 2.6.2-1 and 2.6.2-2 were made from the `support/2.6.2` branch. + +## Coding + +### 🌐 Translations + +A [dedicated page](https://www.itophub.io/wiki/page?id=latest%3Acustomization%3Atranslation) is available in the official wiki. + +### Where to start ? + +1. Create a fork from our repository (see [Working with forks - GitHub Help](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks)) +2. Create a branch in this fork, based on the develop branch +3. Code ! + +Do create a dedicated branch for each modification you want to propose : if you don't, it will be very hard to merge back your work ! + +Most of the time you should base your developments on the develop branch. +That may be different if you want to fix a bug, please use develop anyway and ask in your PR if rebase is possible. ### 🎨 PHP styleguide @@ -106,7 +172,7 @@ Please follow [our guidelines](https://www.itophub.io/wiki/page?id=latest%3Acust Please create tests that covers as much as possible the code you're submitting. -Our tests are located in the `test/` directory, containing a PHPUnit config file : `phpunit.xml.dist`. +Our tests are located in the `tests/` directory, containing a PHPUnit config file : `phpunit.xml.dist`. ### Git Commit Messages @@ -138,14 +204,14 @@ When your code is working, please: * Rebase your branch on our repo last commit, * Create a pull request. _Detailed procedure to work on fork and create PR is available [in GitHub help pages](https://help.github.com/articles/creating-a-pull-request-from-a-fork/)_. * Pull request description: mind to add all the information useful to understand why you're suggesting this modification and anything necessary to dive into your work. Especially: - - Bugfixes: exact steps to reproduce the bug (given/when/then), description of the bug cause and what solution is implemented - - Enhancements: use cases, implementation details if needed -* Mind to check the "[Allow edits from maintainers](https://docs.github.com/en/github-ae@latest/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork)" option ! (note that if you are working with an org fork, this option [won't be available](https://github.com/orgs/community/discussions/5634)) - + - Bugfixes: exact steps to reproduce the bug (given/when/then), description of the bug cause and what solution is implemented + - Enhancements: use cases, implementation details if needed +* Mind to check the "[Allow edits from maintainers](https://docs.github.com/en/github-ae@latest/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork)" option ! (note that if you are working with an org fork, this + option [won't be available](https://github.com/orgs/community/discussions/5634)) ## 🙏 We are thankful -We are thankful for all your contributions to the iTop universe! As a thank you gift, we will send stickers to every iTop (& extensions) contributors! +We are thankful for all your contributions to the iTop universe! As a thank-you gift, we will send stickers to every iTop (& extensions) contributors! We have one sticker per contribution type. You might get multiple stickers with one contribution though :) @@ -157,8 +223,4 @@ We have one sticker per contribution type. You might get multiple stickers with * Graduated: Follow a Combodo's iTop training * Ambassador: Outstanding community contributors * Beta tester: Test and give feedback on beta releases -* Extension developer: Develop and publish an extension - -Here is the design of each stickers for year 2024: - -![iTop stickers 2024](.doc/contributing-guide/2024.contributing-stickers-side-by-side.png) +* Extension developer: Develop and publish an extension \ No newline at end of file