From e22f687c821e219b59c5350b7e12447c65e635c1 Mon Sep 17 00:00:00 2001 From: Victor Poughon <victor.poughon@cnes.fr> Date: Thu, 1 Feb 2018 09:02:21 +0000 Subject: [PATCH] DOC: Add CONTRIBUTING and PSC docs --- CONTRIBUTING.md | 99 +++++++++++++++++ PSC.md | 284 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 10 +- 3 files changed, 390 insertions(+), 3 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 PSC.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..4e74ed2ba5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,99 @@ +# How to contribute to Orfeo ToolBox + +Thank you for taking the time to contribute to OTB! This document will guide you +through the workflow and best practices you need to know to send your +contribution. + +There are many ways to contribute to OTB: + +* [Reporting a bug](#reporting-bugs) +* [Making a feature request](#feature-requests-and-discussions) +* [Improving documentation](#documentation-improvements) +* [Contributing code (C++, Python, CMake, etc.)](#code-contribution) +* [Publishing a remote module](#remote-modules) + +Our main workflow uses GitLab for source control, issues and task tracking. We +use a self-hosted gitlab instance: + +[`https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb`](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb) + +Remember to check out also our [developers mailing list](https://groups.google.com/forum/?hl=fr#!forum/otb-developers/join), +where we discuss some features, improvements and high level project planning. +You are welcome to ask questions there as a beginner or future OTB contributor! + +## Reporting bugs + +If you have found a bug, you can first [search the existing issues](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/issues) +to see if it has already been reported. + +If it's a new bug, please [open a new issue on GitLab](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/issues). +The 'Bug' issue template will help you provide all important information and +help fixing the bug quicker. Remember to add as much information as possible! + +## Feature requests and discussions + +Feature requests are welcome! Generally you are welcome to simply [open an issue](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/issues) +and discuss your idea there. + +For complex and potentially controvertial ideas, we use Request for Comments. +RFCs are normal issues but which will need more discussion from the community +and usually a formal PSC vote. For this, use the 'Request for Comments' issue +template on gitlab. Older RFCs live on the [wiki](https://wiki.orfeo-toolbox.org/index.php/Requests_for_Comments). +More long term ideas are collected on the wiki [Wishlist](https://wiki.orfeo-toolbox.org/index.php/Wishlist). + +For more peripheral contributions which do not belong in the main OTB +repository [Remote Modules](#remote-modules) are also a great option. + +## Documentation improvements + +The two main OTB documentations are the [Software Guide](https://www.orfeo-toolbox.org/SoftwareGuide/index.html) +and the [CookBook](https://www.orfeo-toolbox.org/CookBook/). Their sources are +hosted in the main OTB repository in the `Documentation/` directory. Then, to +contribute documentation use the same workflow as for code contributions (see +below). + +See also the [Compiling documentation](https://wiki.orfeo-toolbox.org/index.php/Compiling_documentation) +wiki page for help on building the Sphinx and Latex source. + +## Code contribution + +The OTB workflow is based on GitLab [Merge Requests](https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html). +Clone the repository, create a feature branch, commit your changes, push the +feature branch to a fork (or the main repository if you are a core developer), +then send a merge request. + +Note that we also accept PRs on our [GitHub mirror](https://github.com/orfeotoolbox/OTB). + +### Commit message + +On your feature branch, write a good [commit message](https://xkcd.com/1296/): +short and descriptive. If fixing an issue or bug, put the issue number in the +commit message so that GitLab can [crosslink it](https://docs.gitlab.com/ce/user/project/issues/crosslinking_issues.html). +You can prefix your commit message with an indicating flag (DOC, BUG, PKG, +TEST, SuperBuild, etc.) or the name of the module you are changing. + +For example, here are some good commit messages: + + BUG: #1701 Warn users if parameter string is unset + DOC: Fix typo in Monteverdi French translation + COMP: Allow GeoTIFF and TIFF to be disabled when no 3rd party drags them + Learning/Unsupervised: Add KMeans Shark implementation + +### Merge request + +Your contribution is ready to be added to the main OTB repository? Send a Merge +Request against the `develop` branch on GitLab using the merge request +template. + +The merge request will then be discussed by the community and the core OTB +team. Larger contributions will require code review and a formal PSC vote. + +## Remote modules + +[Remote Modules](https://wiki.orfeo-toolbox.org/index.php/Remote_Modules) are the prefered way if your contribution is about adding new classes or +application to bring new features to OTB. Remote modules are just like regular +modules, except they are not distributed inside OTB source code. Under some +conditions (dependencies, official acceptance process, etc.), we are also able +to distribute your remote module in the official standalone binaries. See [the wiki](https://wiki.orfeo-toolbox.org/index.php/Remote_Modules) +for more information. + diff --git a/PSC.md b/PSC.md new file mode 100644 index 0000000000..77c3bc6468 --- /dev/null +++ b/PSC.md @@ -0,0 +1,284 @@ +# Project Steering Committee + +This document describes the Project Steering Committee of the Orfeo ToolBox. + +## PSC scope + +The aim of the **OTB Project Steering committee (PSC)** is to provide +high level guidance and coordination for the ORFEO ToolBox. + +It provides a central point of contact for the project and arbitrates +disputes. It is also a stable base of “institutional knowledge†to the +project and tries its best to involve more developers. + +It should help to guarantee that OTB remains open and company neutral. + +### Roadmaps + +The PSC gathers and publishes high level roadmaps for OTB: + +- Feature roadmap +- Technical roadmap (developer and coding guidelines and workflows, + target systems, packaging ...) +- Infrastructure roadmap (SCM, wiki, dashboard ...) + +The PSC also publishes the guidelines and the acceptance policy for +feature requests. It enforces them. It monitors and approves new feature +requests. + +### Communication + +The PSC coordinates communication actions: + +- Ensures that the wiki is up-to-date, +- Ensures that the website is up-to-date and proposes new content, +- Ensures regular posting on the blog and social networks, +- Keeps track of opportunities to communicate: Symposium and events + where OTB should be represented, +- Keeps track of opportunities from communities: Google Summer of Code + project, link with other OSGeo and FOSS projects, +- Is responsible for the organization of events around OTB (i.e. users + meetings and hackathon). + +### User support and documentation + +The PSC ensures that users are given an appropriate support: + +- Ensures that support is working (unanswered questions, questions + from other places than the user list ...) +- Proposes addition to the documentation based on users feedback, +- Proposes new features for the roadmap based on users feedback, +- Proposes new ways for support and documentation + +### Contribution management + +The PSC publishes the guidelines and acceptance policy for +contributions. It enforces them. + +It monitors and approves new proposals. + +It ensures that contribution is as easy as possible, by monitoring +technical means for contribution and proposing evolutions to guidelines, +policies and means. + +### Release planning + +The PSC publishes release guidelines and policies, and enforces them. + +The PSC puts together the next Release roadmap and proposes a planning. +It is then responsible for the release preparation. + +The final approval for a release is given by the PSC (motion proposed to +the otb-developers mailing list). + +### Handling of legal issues + +The PSC is responsible for addressing any issue about copyright or +licensing that may occur, and most importantly, it is responsible for +taking preventive actions about those issues. + +## How does the PSC work? + +This section describes how the PSC works. It is inspired by existing +governance statuses in other open source community projects related to +OTB like +[GDAL](https://trac.osgeo.org/gdal/wiki/GovernanceAndCommunity), +[Quantum +GIS](http://www2.qgis.org/en/site/getinvolved/governance/index.html) or +[GRASS](http://trac.osgeo.org/grass/wiki/PSC). + +### PSC members + +All members have equal standing and voice in the PSC. The PSC seats are +non-expiring. PSC members may resign their position, or be asked to +vacate their seat after a unanimous vote of no confidence from the +remaining PSC members. + +The expectations on PSC members are: + +- Be willing to commit to the OTB development effort +- Be responsive to requests for information from fellow members +- Be able and willing to attend on-line meetings +- Act in the best interests of the project + +It is important to note that the PSC is not a legal entity! + +### Roles + +Members can be assigned roles corresponding to each category of the PSC +scope described above. + +Being assigned a role does not mean undertaking all necessary actions, +but rather ensuring that actions will be undertaken. + +In addition to their specific roles, members of the PSC commit to +participate actively in discussions and votes. + +One member of the PSC is designated as the Chair and is the ultimate +adjudicator in case of deadlock or irretrievable break down of +decision-making, or in case of disputes over voting. + +### When is a PSC vote required? + +A vote of the PSC is required in the following cases: + +1. Merge Request +2. Addition or removal of PSC members (including the selection of a new + Chair) +3. Release process + +In addition, a vote can be summoned for: + +1. Changing PSC rules and processes +2. Anything else that might be controversial + +#### Merge Request + +A Merge Request describes a change in Orfeo ToolBox code, API, +infrastructure or processes that need to be submitted to the PSC vote: + +- Anything that could cause backward compatibility issues, +- Adding substantial amounts of new code, +- Changing inter-subsystem APIs, or objects, + +It should describe : + +1. What changes will be made and why they will make a better Orfeo + ToolBox +2. When will those changes be available (target release or date) +3. Who will be developing the proposed changes + +Those elements can be provided in an email to the developer list or on a +git hosted platform (GitLab, GitHub, etc.). + +#### Add or remove PSC members + +To be eligible for membership in the PSC, a person should demonstrate +**a substantial and ongoing involvement in OTB**. The PSC is not only +composed of OTB developers as there are many ways to join and contribute +to the project. Anyone is eligible to be nominated to the OTB PSC. +Ideally, nominees would be OTB users or developers who have a deep +understanding of the project. In addition, nominees should meet the +qualifications set forth in this document. Anyone can submit a +nomination. + +#### Release phases + +The release manager (the PSC member in charge of release planning) +submits to vote the following release decisions: + +1. Date of the next release +2. Codename of the next release +3. Date and revision of Release Candidate +4. Date and revision of Final Release +5. Date and revision of bug-fixes Release + +### Process + +- Proposals are written up and submitted on the otb-developers mailing + list for discussion and voting, by any interested party, not just + committee members. Proposals are available for review for at least + three days before a vote can be closed. It is acknowledged that some + more complex issues may require more time for discussion and + deliberation. +- Respondents may vote “+1†to indicate support for the proposal and a + willingness to support implementation. +- Respondents may vote “-1†to veto a proposal, but must provide + argumented reasoning and alternate approaches to resolve the problem + within the two days. +- A vote of -0 indicates mild disagreement, but has no effect. A 0 + indicates no opinion. A +0 indicates mild support, but has no + effect. +- Anyone may comment and vote on proposals on the list, but only + members of the PSC's votes (including the Chair) will be counted + (“eligible votersâ€). +- A proposal will be accepted if it receives at least +2 (including + the proponent) and no vetos (-1) +- If a proposal is vetoed, and it cannot be revised to satisfy all + parties, then it can be resubmitted for an override vote in which a + majority of all eligible voters indicating +1 is sufficient to pass + it. Note that this is a majority of all committee members, not just + those who actively vote. +- Upon completion of discussion and voting the proposers should + announce whether they are proceeding (proposal accepted) or are + withdrawing their proposal (vetoed). +- The Chair adjudicates in cases of disputes about voting. + +A summary of discussions is published in a dedicated section of the wiki +[Requests for Changes](Requests_for_Changes "wikilink"). + +## Current members and roles + +In March 2015, CNES nominated 3 persons deeply involved in OTB as +initial PSC members. They are responsible for defining PSC rules and +establishing a fully functioning PSC. PSC has now 4 members. + +**Name** | **Affiliation** | **Email** | **Role** | +----------------------------|------------------|----------------------------------|--------------------------------------------| +Manuel Grizonnet (resigned) | CNES | manuel.grizonnet AT cnes DOT fr | Infrastructure, legal issues | +Rémi Cresson | IRSTEA | cresson.r AT gmail DOT com | Release Manager for release 5.2 | +Guillaume Pasero | CS-SI | guillaume.pasero AT c-s DOT fr | release planner | +Jordi Inglada (resigned) | CNES/CESBIO | jordi.inglada AT cesbio DOT eu | | +Julien Michel | CNES | julien.michel AT cnes DOT fr | Communication, contributions | +Victor Poughon | CNES | victor.poughon AT cnes DOT fr | User support and documentation, roadmaps | + +## Release manager + +A **release manager** is nominated for each release. Nomination is made +shortly after previous release announcement. A **backup release +manager** is also nominated, to assist and possibly step in if the +official release manager is not available. The **release manager** and +his/her backup can be a member of the PSC, but also another member of +otb-developers list willing to take the spot. + +The **release manager** is in charge of : + +1. Listing and tracking all major features proposed for next release + (from call for contribution in the early phase and then approved + RFCs) +2. Planing release date and ensures sync with RFCs execution, +3. Approving feature branch merges (if possible, leave at least 3 days + between RFC submission and merge, so that people have time to do a + review) +4. Actually merging feature branches when authors do not have commit + rights (github pull request for instance) +5. Tracking remote module that can be candidate for official inclusion + in next release, and ensuring they will be included (see + [Contributors guidelines](Contributors_guidelines "wikilink")) +6. Submitting the start of the [release + process](How_to_Release "wikilink") to PSC vote +7. Ensuring proper execution of [release + process](How_to_Release "wikilink") + +**Feature freeze:** Starting the release process is also called *feature +freeze* which describes the period between the creation of the release +branch and the announcement of the release. It's an important time for +the RM who should ensures the proper execution of the release process +and facilitate the communication between developers. The RM is among +other things responsible of gathering feedback on bugs that need to be +fixed before the release, making a list that is public to be able to +follow progression of the release process. + +**Remember:** all new features must be submitted by Merge Requests and +approved by the PSC. The release manager only approves the feature +branches merge. + +### Feature branch merge acceptance checklist + +1. The feature branch corresponds to an [approved + Merge Request](Project_Steering_Committee#Process "wikilink") +2. The feature branch is synched with develop +3. The feature branch is tested on the dashboard (see + [here](#NightlyFeatureBranches "wikilink")) and has no major failure + (compilation errors, tremendous amount of warning or failing tests, + segfault or not executed tests) +4. Feature branch author are available during days following the merge + to analyse dashboard and fix things in case of unexpected issues + after the merge + +It is important to note that a feature branch should be kept relatively +small and does not necessarily correspond to the full implementation of +a RFC. Small consistent branches implementing parts of RFC can be merged +early. Further evolutions and implementations of the RFC can be done by +continuing the feature branch or opening new branches, and approval of +Release Manager should be requested again before merging. diff --git a/README.md b/README.md index 2842c132d8..7a3a7e734f 100644 --- a/README.md +++ b/README.md @@ -23,10 +23,10 @@ not a black box! * [OTB's website](https://www.orfeo-toolbox.org/) * [Documentation](https://www.orfeo-toolbox.org/documentation/) * [Downloads](https://www.orfeo-toolbox.org/download/) -* [Public git repositories](https://gitlab.orfeo-toolbox.org/orfeotoolbox) +* [Public git repositories](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb) * [GitHub mirror](https://github.com/orfeotoolbox/) * [Build status](http://dash.orfeo-toolbox.org/index.php?project=OTB) -* [Bug tracker](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/issues?label_name%5B%5D=general) +* [Bug tracker](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/issues) * [Wiki](http://wiki.orfeo-toolbox.org/index.php/Main_Page) * [Task tracking](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/issues) @@ -37,10 +37,14 @@ joining our community and mailing lists. [https://www.orfeo-toolbox.org/community/](https://www.orfeo-toolbox.org/community/) ### Contributing -Please see the wiki for contributors guidelines. +Please see [CONTRIBUTING.md](CONTRIBUTING.md) for contributors guidelines. ### License Please see the license and the Copyright directory for legal issues on the use of the software. ### Issues Please report any issue you might encouter to [our bugtracker](https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb/issues). + +### Governance + +The Orfeo ToolBox project is governed by the [Project Steering Committee](PSC.md) and its members. -- GitLab