Contributing

Contributing to EGI documentation

Thank you for taking the time to contribute to this project. The maintainers greatly appreciate the interest of contributors and rely on continued engagement with the community to ensure that this project remains useful. We would like to take steps to put contributors in the best possible position to have their contributions accepted. Please take a few moments to read this short guide on how to contribute; bear in mind that contributions regarding how to best contribute are also welcome.

Style guide

Feedback and Questions

If you wish to discuss anything related to the project, please open a GitHub issue or start a topic on the EGI Community Forum. The maintainers will sometimes move issues off from GitHub to the community forum if it is thought that longer, more open-ended discussion would be beneficial, including a wider community scope.

Contribution Process

All contributions have to go through a review process, and contributions can be made in two ways:

  • for simple contribution you can contribute from your browser by clicking the pencil Edit this file icon shown at the top of a page that you are viewing (See GitHub documentation). You will be guided through the required steps. Be sure to quickly save your changes quickly as the repository may be updated by someone else in the meantime.
  • for more complex contributions and when you want to preview and test changes locally you should fork the repository as documented below in the Using git and GitHub page.

Contributing via a Pull Request

Before proposing a contribution via the so-called Pull Request (PR), ideally there is an open issue describing the need for your contribution (refer to this issue number when you submit the Pull Request). We have a 3 steps process for contributions.

  1. Fork the project if you have not, and commit changes to a git branch. Documentation on building the documentation locally is available in the README.md
  2. Create a GitHub Pull Request for your change, following the instructions in the Pull Request template.
  3. Perform a Code Review with the maintainers on the Pull Request.

Pull Request Requirements

  1. If the PR is not finalised mark it as draft using the GitHub web interface, so that it’s clear it’s not yet ready to be reviewed.
  2. Explain your contribution in plain language. To assist the maintainers in understanding and appreciating your pull request, please use the template to explain why you are making this contribution, rather than just what the contribution entails.

Code Review Process

Code review takes place in GitHub pull requests. See this article if you’re not familiar with GitHub Pull Requests.

Once you open a pull request, automated checks will verify the style and syntax of your changes and maintainers will review your code using the built-in code review process in GitHub Pull Requests.

The process at this point is as follows:

  1. Automated syntax and formatting checks are run using GitHub Actions, successful checks are a hard requirement, but maintainers will help you addressing reported issues.
  2. A maintainer will review your code and merge it if no changes are necessary. Your change will be merged into the repository’s master branch.
  3. If a maintainer has feedback or questions on your changes then they will set request changes in the review and provide an explanation.

Release cycle

The documentation is using a rolling release model, all changes merged to the master branch are directly deployed in the live production environment.

Master branch is always available. Tagged versions may be created as needed following Semantic Versioning as far as applicable.

Community

EGI benefits from a strong community of developers and system administrators, and vice-versa. If you have any questions or if you would like to get involved in the wider EGI community you can check out:

This file has been modified from the Chef Cookbook Contributing Guide.


Style guide

Style guide for EGI documentation

Syntax

Syntax guide for EGI documentation

Using Git and GitHub

First steps with Git and GitHub