Skip to content
Snippets Groups Projects
Commit e22f687c authored by Victor Poughon's avatar Victor Poughon
Browse files

DOC: Add CONTRIBUTING and PSC docs

parent d0e48dc2
No related branches found
No related tags found
1 merge request!1DOC: Add CONTRIBUTING and PSC docs
Hide whitespace changes
Inline Side-by-side
CONTRIBUTING.md 0 → 100644
+ 99
− 0
View file @ e22f687c
# 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.
PSC.md 0 → 100644
+ 284
− 0
View file @ e22f687c
# 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.
README.md
+ 7
− 3
View file @ e22f687c
......@@ -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.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment