OpenConext can only achieve the goal of developing a system for the community if the project is supported by the community. Contributions can take many forms, depending on your ambitions and your level of interest.
There are several ways to join the OpenConext community or the OpenConext project efforts.
- Discuss… join the OpenConext discussion list. You can find information about the discussion list here.
- Send an issue to the issue tracker on Github
- Contribute… Documentation about OpenConext will be maintained on this site. You are encouraged to review, critique and offer your suggestions about the project.
Code contributions can be done on the public Github repository (https://github.com/openconext) using these simple rules:
- Get yourself a Github account.
- Submit your patches in the format one patch per issue.
- The OpenConext community can review and comment patches.
- When a patch is reviewed by the community and is ready to be committed, the OpenConext code maintainer can commit the patch to the OpenConext code repository.
In addition to these rules
- Make sure your code does work.
- We require that variable and subroutines, as well as comments in the code be made in English. While we appreciate the talents of the worldwide community, we cannot support code that we cannot read.
- If there is not already an item in the issue tracking system, create one. Assign the tracking item to yourself.
- Submit the patch, along with a “commit message” referring to the (one) issue of the Github OpenConext tracking system.
- Code submission guideline are copied from following sources and partly adapted :
- Build… you may decide to invest in OpenConext and contribute resources toward the development effort. We hope to provide more ways for people to get involved in the project. For now, the best way to stay connected is through joining the mailing list and participating in meetings.
How to contribute to OpenConext
We have made the assumption that we want to ‘register’ any changes, change & feature requests and issues/bugs as close to the source code as possible. At the same time, especially for changes, we feel it should be clear what is going on and why, so some overview is needed.
We therefore propose the following as the modus operandi for contributing to OpenConext (largely based on the Apache Foundation):
- Discuss the change proposal on the openconext-dev list. Describe what it is you want and why you want is. Even if it is a deeply technical thing you want to change, please also try to provide a ‘layman’s’ description of the change.
- At some point rough consensus will be reached on the list. Now proceed by describing the result of the discussion in the github wiki at the relevant component. If the change impacts several components, or e.g. create a new one, please use the OpenConext/OpenConext repository wiki to describe these.
- Create issues in github for the work that needs to be done to achieve the envisioned change.
- When you are ready to commit code, create a pull request to submit code that belongs to specific issues. The code will be reviewed and commented upon by the community, and based on that (for now) SURFnet will officially accept or refuse the code.
- Detailed information on how OpenConext works with GitHub, branches etc, is documented in the article Releases.
We envision that SURFnet will not remain the sole party in the QA role. Based on successful contributions we will start accepting non-SURFnet employees as committers.
Contributing bug/issue reports
- Discuss the bug/issue openconext-users list. Describe what it is you found, and how to reproduce that. Even if it is a deeply technical thing you think is creating the issue, please also try to provide a ‘layman’s’ description of the change.
- If from the discussions on the list it becomes clear that it is indeed a bug, register this bug by creating an issue in github.
- If the fix for the bug/issue is small you may already have written a patch. If so please create a pull request and add a pointer to the issue as part of the request.
For now, SURFnet will shepherd the bugs and issues posted (which does not mean we will also fix them!) Again we do not envision SURFnet to remain in this role
Working with External components
(Janus, Grouper, SimpleSAMLphp, LAMP and Tomcat, Shibboleth)
As you are probably aware, OpenConext tries not to rebuild what is already available. Therefore, it relies on several existing open source projects and communities, which we will refer to as ‘Upstream’ from now on. Some changes and bugs you find may be related to or caused by issues in upstream projects. If you encounter such an issue, we propose to use whatever methodology the upstream project is using to interact with them. However, at the same time, we request you to please create an issue in github for either the change of the bug as well. Please add a reference to the upstream issue or change to make sure the relations can be traced back upstream
Contributing to Documentation
If you want to contribute to the documentation of OpenConext, please make this known via the openconext-users list. As a rule of thumb, any documentation on the technical workings of a software component should go together with the actual code in github.
Documentation on use of applications, as well as documentation and use cases on using the platform as a whole should be committed to the documentation sections of this OpenConext site.