CONTRIBUTING.md

Contributing guide

Want to contribute? Great!

All contributions are more than welcome ! This includes bug reports, bug fixes, enhancements, features, questions, ideas, and documentation.

This document will hopefully help you contribute to pgagroal.

• Legal
• Reporting an issue
• Setup your build environment
• Building the master branch
• Before you contribute
• Code reviews
• Coding Guidelines
• Discuss a Feature
• Development
• Code Style

Legal

All contributions to pgagroal are licensed under the The 3-Clause BSD License.

Reporting an issue

This project uses GitHub issues to manage the issues. Open an issue directly in GitHub.

If you believe you found a bug, and it's likely possible, please indicate a way to reproduce it, what you are seeing and what you would expect to see. Don't forget to indicate your pgagroal version.

Setup your build environment

You can use the follow command, if you are using a Fedora based platform:

dnf install git gcc cmake make libev libev-devel openssl openssl-devel systemd systemd-devel python3-docutils

in order to get the necessary dependencies.

Building the master branch

To build the master branch:

git clone https://github.com/agroal/pgagroal.git
cd pgagroal
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
make
cd src
cp ../../doc/etc/*.conf .
./pgagroal -c pgagroal.conf -a pgagroal_hba.conf

and you will have a running instance.

Before you contribute

To contribute, use GitHub Pull Requests, from your own fork.

Also, make sure you have set up your Git authorship correctly:

git config --global user.name "Your Full Name"
git config --global user.email your.email@example.com

We use this information to acknowledge your contributions in release announcements.

Code reviews

GitHub pull requests can be reviewed by all such that input can be given to the author(s).

See GitHub Pull Request Review Process for more information.

Coding Guidelines

• Discuss the feature
• Do development
  • Follow the code style
• Commits should be atomic and semantic. Therefore, squash your pull request before submission and keep it rebased until merged
  • If your feature has independent parts submit those as separate pull requests

Discuss a Feature

You can discuss bug reports, enhancements and features in our forum.

Once there is an agreement on the development plan you can open an issue that will used for reference in the pull request.

Development

You can follow this workflow for your development.

Add your repository

git clone git@github.com:yourname/pgagroal.git
cd pgagroal
git remote add upstream https://github.com/agroal/pgagroal.git

Create a work branch

git checkout -b mywork master

During development

git commit -a -m "[#issue] My feature"
git push -f origin mywork

If you have more commits then squash them

git rebase -i HEAD~2
git push -f origin mywork

If the master branch changes then

git fetch upstream
git rebase -i upstream/master
git push -f origin mywork

as all pull requests should be squashed and rebased.

In your first pull request you need to add yourself to the AUTHORS file.

Code Style

Please, follow the coding style of the project.

You can use the uncrustify tool to help with the formatting, by running

./uncrustify.sh

and verify the changes.