Developing phpCAS

Owned by Pascal AUBRY
Last updated: Aug 01, 2014 by Adam FrancoVersion comment
4 min read

Submitting and/or fixing issues

Create an issue

Go to the Bug-tracker at https://github.com/Jasig/phpCAS/issues and create a new issue.

If you just are submitting a bug report an not a fix, this is the only thing you need to do. Thanks!

Develop your fix or feature

If you can develop a fix for your issue, we welcome such contributions. Here are detailed steps on how to develop your fix:

  1. Fork our Git repository so that you can publish your changes to us:

    1. Create a free Github account if you don't already have one.
    2. Go to https://github.com/Jasig/phpCAS
    3. Click the "Fork" button on the toolbar at the top-right of the screen. This will create your own clone of our repository where you can push branches and commits that fix issues.

  2. Clone your repository to your development workspace.

    1. Copy the Read+Write Git url for your workspace, usually you will want to use the SSH version which will look like: git@github.com:yourname/phpCAS.git
    2. Clone your repository with the Git command:
      git clone git@github.com:yourname/phpCAS.git
      This will create a working directory called phpCAS/ that contains all of the git metadata and a working copy of the files.

  3. Create a branch for developing your fix or feature.

    Creating a branch will make your work readily identifiable when you publish it and allow you to work on multiple issues at one time.
    If possible, please create branches with your Github issue id and a descriptive name, e.g: 129-Service_URL_bug
    Note: There are cases where you won't have an issue id, such as when you are just prototyping a feature or fix in your own repository and aren't sure if you will want to submit it as a pull request. In these cases just pick a branch name that is descriptive, e.g. Service_URL_Bug.

    To create a branch use the Git command. We'll use "129" as the issue id for this example, but please use your real issue id:

        git checkout -b 129-Service_URL_bug

    This will create a new branch named '129-Service_URL_bug' and check it out. Any commits you make after this command will be committed to this branch.

  4. Commit your changes to your branch as you develop your feature.

    As you work on your fix or feature, commit your work to your branch. At this point, your commits are not shared with anyone, so it is ok if they are not fully ready for usage by the world.

    Commit tips:
    1. Commit Messages:
      Take some time to provide a good commit message that describes your commit. The first line of the commit message should be a summary not more than about 80 characters long and include the issue id. The summary should be followed by a blank line and then a longer description, with lines not longer than about 80 characters. Please include your issue ID in the message preceeded by a '#' this will make it readily identifiable as well as automatically link it to the Github issue if and when you push your commit to Github. Here is an example of a good commit message:

          #126 - Global variables are now private static variables in phpCAS.

          This will prevent poorly written clients from accidentally accessing the CAS_client

          or other 'global' variables and for them to go through the API.

          $PHPCAS_AUTH_CHECK_CALL currently needs to be public since it is accessed by both

          phpCAS and CAS_Client. This should be refactored to make it not public or

          at least not public in the phpCAS class.

    2. There is no limit to the number of commits that make up a feature or fix.
    3. If you have a large fix or feature, try to break it up into commits that are related to each other and make sense. A good rule of thumb is that the commit message should describe a single thing or reason and all code changes should apply to that reason. Here is a sequence of commits to give you some examples of appropriately-sized commits:

Submit your fix or feature

  1. Push your branch to your fork on Github.

    Once you have your fix in a state that you would like to share it or get feedback, push it to your Github repository so that it is visible to the world.

    git push origin 129-Service_URL_bug

    This will create a branch in your Github repository named  '129-Service_URL_bug' or whatever your branch and issue are named. It will also automatically create 'mention' links in any Github Issue referenced in the commit messages.

  2. Submit a "Pull Request" through Github.

    Github provides a nice tool for tracking the integration of new work. Look for the "Pull Request" button in the Github toolbar. When submitting pull requests, please make sure that the issue id is in the subject line preceeded by a '#', (e.g. "Fix for #129 - Service URL bug")

Source Repository On Github

https://github.com/Jasig/phpCAS

Bugtracker

https://github.com/Jasig/phpCAS/issues

Recommended environment

phpCAS developers recommend the use of Eclipse to get a nice programming environment:

  • ant 1.6.1+
  • Doxygen (to generate the source documentation, a ant_doxygen.jar file is provided in the utils/ folder)
  • PEAR's PEAR_PackageFileManager package (required for makepackage.php)
  • PHP to run the makepackage.php script used to generate the PEAR package
  • PDT eclipse package, maybe, to get PHP support ?