When creating a new feature or bug fix, you will typically start by ensuring you are on the develop branch and use the following
command to create your new branch:
git checkout -b <your-branch-name>
If there is a Jira ticket for your task then using that ticket number and title is a good candidate for your branch name but as long as it is clear what your branch is for then you can use anything you wish.
Note that you do not always have to branch off of develop, for instance if you are making a change to something that isn't merged
into develop yet you will want to branch off of that other existing branch. It is important to remember which branch you branched
off of so that you merge back into that branch.
Once your changes are committed and pushed up, you are ready to make a Pull Request on GitHub. In your web browser, navigate to
https://github.com/PDGA/php-exceptions/pulls and click New Pull Request.
Ensure that the branch selected in the base dropdown is the branch you branched off of, and the option selected in the compare
dropdown is your branch. Click Create Pull Request and add a description of your change in the Add a description section.
Make sure you select at least two people as reviewers and then click Create Pull Request below the description box
to open the Pull Request.
Once at least two people have approved your Pull Request it may be merged. There are two ways to do this:
You can either use the GUI on GitHub to automatically merge your branch into the branch you selected as base
and then subsequently delete your branch, or you can use the git command line to do the same.
The Merge pull request button on GitHub is at the bottom of the main Pull Request page and once clicked it
will turn into a Delete Branch button. After the branch is deleted you should change which branch you are working
in locally to the one you select as base and run the following commands:
git fetch -p
git pull
To use the git command, first change your current working branch to your base branch. Then use the following
command to merge your branch.
git merge <your-branch-name>
Once the merge is complete and any conflicts have been resolved and committed you must push up the base branch.
NOTE: Changes can not be committed and pushed directly to develop from the command line, so if your base branch was
develop please see the above instructions for using the GitHub GUI for merging.
At this point you can delete your branch from the origin:
git push -d origin <your-branch-name>
After deleting the branch from the origin, either manually or via GitHub, make sure to delete it locally:
git branch -d <your-branch-name>
To release a new version of the repository, all changes need to be merged into develop via a Pull Request.
Changes can not be committed and pushed directly to develop from the command line, so a Pull Request is required.
When you intend to release a new version you will also want to update the CHANGELOG.md file with a list of changes
made under the new version number you intend to release (See below for information about version numbers).
Once all changes have been merged into develop it needs to be merged into main, again via a Pull Request.
Once everything is merged into main a new tag can be created for the repository and pushed.
A new tag for the repository should be created using the following naming scheme:
<major-version.minor-version.bug-fix>
The major version should be incremented whenever breaking changes are added to the repository code. The minor version should be incremented when non breaking, non bug fix changes are made to the repository code. The bug fix version should be incremented when only bug fixes are added to the repository code.
Note that incrementing a version number sets all version number to the right of that number to 0.
For example, if a breaking change is made to version 1.4.29 you would go from 1.4.29 to 2.0.0, NOT 2.4.29.
To create a new tag, use the following command from the command line:
git tag -a <new-tag-version> -m "<a comment about what this version is>"
followed by
git push -u origin <new-tag-number>
This package can be used in other PHP applications via Composer. It is available for inclusion via Composer from Packagist.
This package is already set up on Packagist, which watches the repository for new tag and automatically creates a new release version for use via Composer (The Packagist page can be found at https://packagist.org/packages/pdga/exception). Therefore, the simple act of pushing a new tag to the repository will trigger a new version to be available in Composer. Sometimes it can take a bit of time for the new version to become available. You can verify that the new version is available on the Packagist page.
To add the package to an application's Composer dependencies, use the following Composer command:
composer require pdga/exception
You will also use the above command to update the package if it is already being used in your application but the major version number has been changed.
If you want to update an existing dependency on this package and only the minor or bug fix version has been changed you can use the following command in that application:
composer update pdga/exception
The above commands are very simple, however there are many options as far as dictating which versions are installed that can be used. For more information see the official Composer documentation.
./bin/composer install
./bin/codesniffer
./bin/codeformatter