Pull Request Guidelines

Table of Contents

• Intro
  • A Word about Git
  • A Word about Github
  • The Gitflow Branching Model and Workflow
• Getting Started
  • Setting up your Development Environment
  • Typical Workflow While Working On Issues
• On To Gitflow

Intro

If you have landed on this page then most likely you would like to contribute to PHP-RBAC, and the entire community thanks you!!!

The following guide will explain the easiest way (hopefully) to get your environment ready to start creating the wunder code that will help make PHP-RBAC even better than it is today!

A Word about Git

When we mention 'Git' we are talking about the DVCS (Distributed Version Control System) that goes by the name of Git.

We will mention 'git' commands, but due to the many Git clients that exist we will not focus on any one specific Git client. To learn more about Git please refer to the Official Git Documentation.

A Word about Github

Github is a website where Software/Library Project can be hosted. Github has many features that ease collaboration between co-developers of a project.

• Github.com:

    "GitHub is the best place to share code with friends, co-workers, classmates, and complete strangers."
  

• Wikipedia.com:

    "GitHub is a web-based Git repository hosting service, which offers all of the distributed revision control and source code management (SCM) functionality of Git as well as adding its own features. Unlike Git, which is strictly a command-line tool, GitHub provides a web-based graphical interface and desktop as well as mobile integration. It also provides access control and several collaboration features such as wikis, task management, and bug tracking and feature requests for every project."
  

Even though we use Git to manage code changes and facilitate collaboration, Git and Github are two different entities.

To learn more about GitHub, take a look at the Official Github Documentation.

The Gitflow Branching Model and Workflow

Please know we have adopted Vincent Driessen's Gitflow Git Branching Model and Workflow. Check out Vincent Driessen' s article "A successful Git branching model" to learn more about it.

If all co-developers follow the Gitflow workflow while working on Pull Requests, development will go much smoother.

When a development team, or a project itself, has clearly defined procedures that every member is aware of, we not only benefit from an increase in productivity, we have also made a step towards minimizing potential confusion and/or chaos.

This is why we politely ask that all co-developers follow these guidelines :-)

Getting Started

Setting up your Development Environment

Follow these steps to "git" started with your development environment.

1. Create a Github account: Signing up for a new GitHub account
2. Set up Git: Set Up Git
3. Fork PHP-RBAC's project repo: Fork A Repo

• PHP-RBAC's Project Repo URL: https://github.com/OWASP/rbac

4. Clone the repo you forked onto your local computer: Cloning a repository
5. Brush up on Git branching: Git Branching - Branches in a Nutshell

Typical Workflow While Working On Issues

• See 'Gitflow' for the official article, and be sure to check out our Gitflow-Cheat-Sheet.
• Use the 'develop' branch to create a new 'topic_branch'.
• Use your 'topic_branch' to work on a single issue.
• Once your 'topic_branch' has been tested and is complete you will need to create and send a PR (Pull Request): Using pull requests.
  • In most cases you will point your PR to PHP-RBAC's 'develop' branch.
• Once your PR has been merged you can then remove your 'topic_branch' locally and on Github.
• Next time you need to work on an issue, do a fetch/rebase from PHP-RBAC's repo to ensure that your local repo is current.

##On To Gitflow

To take a quote from https://datasift.github.io:

    "GitFlow is a branching model for Git, created by [Vincent Driessen](http://nvie.com/about/). It has attracted a lot of attention because it is very well suited to collaboration and scaling the development team."

Gitflow is large enough of a topic to warrant an entire discussion on it's own. These two resources will get you up to speed in no time:

• PHP-RBAC's Gitflow crash course/cheat-sheet/reference: PHP-RBAC's Gitflow Cheat Sheet
• The original article introducing Gitflow: A successful Git branching model

Note: If you notice any errors, broken links or would like to add information to this article please feel free to click the "Edit" button located to the left of this page's title and make your changes. Any and all changes and additions would be greatly appreciated by the entire PHP-RBAC community!!!