CONTRIBUTING.md

Contribution guidelines

SimpleSAMLphp welcomes all contributions. It is impossible to make a product like this without the efforts of many people, so please don't be shy and share your help with us. Even the tiniest contribution can make a difference!

These guidelines briefly explain how to contribute to SimpleSAMLphp effectively and consistently, making sure to keep high quality standards and making it easier for you to contribute.

Team members

Currently, the core team members are:

• Jaime Pérez Crespo, maintainer and main developer, UNINETT jaime.perez@uninett.no
• Tim van Dijen, main developer
• Thijs Kinkhorst, main developer

Two other persons are listed here for historical reasons, even though they are no longer involved in the project:

• Andreas Åkre Solberg, architect and original developer, UNINETT andreas.solberg@uninett.no
• Olav Morken, architect and main developer, UNINETT olav.morken@uninett.no

We have been lucky enough to have so many people help us through the years. SimpleSAMLphp wouldn't have reached so far without them. We want to thank them from here, but unfortunately they are so many it is nearly impossible to mention all of them. Here is a Github page that summarizes everyone's contributions.

Big thanks to you all!

First things first

Before embarking yourself in a contribution, please make sure you are familiar with the way SimpleSAMLphp is written, the way it works, and what is required or not.

• Make sure to read the documentation. If you use the search engine in the website, please verify that you are reading the latest stable version. If you want to make a change, check the development branch of the documentation.
• If you have a question about using SimpleSAMLphp, please use the mailing list.
• If you have a question about developing SimpleSAMLphp, please ask in the development mailing list.
• If you think you have discovered a bug, please check the issue tracker and the pull requests to verify it hasn't been reported already.

Contributing code

New features are always welcome, provided they will be useful to someone apart from yourself. Please take a look at the list of issues to see what people are asking for. Our roadmap might also be a good place to start if you do not know exactly how you can contribute.

When submitting a pull request, please make sure to account for:

Coding standards

• Respect the coding standards. We try to comply with PHP's PSR-12. Pay special attention to the rules below:
  • Lines should not be longer than 80 characters.
  • Use 4 spaces instead of tabs.
  • Keep the keywords in lowercase, including true, false and null.
  • Make sure your classes work with autoloading.
  • Never include a trailing ?> in your files.
  • The first line of every file must be <?php.
  • Use namespaces if you are adding new files.
• Do not include too many changes in every commit. Commits should be focused and address one single problem or feature. By having multiple, small commits instead of fewer large ones, it is easier to track what you are doing, revert changes in case of an error and help you make changes if needed.
• Try to write clean commit messages, largely based on the seven rules:
  • Write a short subject line, followed by a blank line and a longer explanation.
  • Prefix the subject line with the component(s) changed, e.g. "docs: Update foo", or "SAML: Don't log bar twice", or "tests: Add tests for quux".
  • Explain what and why in the commit message, not just how. Things that seem obvious now might become quite confusing when rediscovered years later.

Comments, comparisons, and simplicity

• Add comments that describe why/how your code works.
• Include complete phpdoc documentation for every property and method you add. If you change a method or property, make sure to update the existing phpdoc accordingly. Do not forget to document all parameters, returned values and exceptions thrown.
• Use strict comparison operators like === and check for specific values when writing tests.
• Avoid big functions, long nested loops or if statements.
• Try to keep backwards-compatibility. Code that breaks current configurations and installations is difficult to deploy, and therefore we try to avoid that as much as possible.