6.5 KiB
Contributing to Carbon
Issue Contributions
Please report any security issue using Tidelift security contact. Tidelift will coordinate the fix and disclosure. Please don't disclose security bugs publicly until they have been handled by us.
For any other bug or issue, please click this link and follow the template: Create new issue
You may think this template does not apply to your case but please think again. A long description will never be as clear as a code chunk with the output you expect from it (for either bug report or new features).
Code Contributions
Where to begin
We use the label good first issue to tag issues that could be a good fit for new contributors, see if there are such issues now following this link:
https://github.com/briannesbitt/Carbon/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
Else, check the roadmap to see what we plan to do in next releases:
https://github.com/briannesbitt/Carbon/issues/1681
Develop locally, then submit changes
Fork the GitHub project and download it locally:
git clone https://github.com/<username>/Carbon.git
cd Carbon
git remote add upstream https://github.com/briannesbitt/Carbon.git
Replace <username> with your GitHub username.
Then, you can work on the master or create a specific branch for your development:
git checkout -b my-feature-branch -t origin/master
You can now edit the "Carbon" directory contents.
Before committing, please set your name and your e-mail (use the same e-mail address as in your GitHub account):
git config --global user.name "Your Name"
git config --global user.email "your.email.address@example.com"
The --global argument will apply this setting for all your git repositories, remove it to set only your Carbon
fork with those settings.
Now you can commit your modifications as you usually do with git:
git add --all
git commit -m "The commit message log"
If your patch fixes an open issue, please insert # immediately followed by the issue number:
git commit -m "#21 Fix this or that"
Use git rebase (not git merge) to sync your work from time to time:
git fetch origin
git rebase origin/master
Please add some tests for bug fixes and features (so it will ensure next developments will not break your code), then check all is right with phpunit:
Install PHP if you haven't yet, then install composer: https://getcomposer.org/download/
Update dependencies:
./composer.phar update
Or if you installed composer globally:
composer update
Then call phpunit:
./vendor/bin/phpunit
Make sure all tests succeed before submitting your pull-request, else we will not be able to merge it.
Push your work on your remote GitHub fork with:
git push origin my-feature-branch
Go to https://github.com/yourusername/Carbon and select your feature branch. Click the 'Pull Request' button and fill out the form.
We will review it within a few days. And we thank you in advance for your help.
Versioning
Note about Semantic Versioning and breaking changes
As a developer, you must understand every change is a breaking change. What is a bug for someone is expected in someone else's workflow. The consequence of a change strongly depends on the usage. Semantic Versioning relies to public API. In PHP, the public API of a class is its public methods. However, if you extend a class, you can access protected methods, then if you use reflexion, you can access private methods. So anything can become a public API if you force it to be. That doesn't mean we should handle any possible usage, else we would have to publish a major release for each change and it would no longer make sense.
So before any complain about a breaking change, be warned, we do not guarantee a strict Semantic Versioning as you may expect, we're following a pragmatic interpretation of Semantic Versioning that allows the software to evolve in a reliable way with reasonable maintenance effort.
Concretely, we consider a change as breaking if it makes fail one of our unit test. We will do our best to avoid incompatibilities with libraries that extends Carbon classes (such as Laravel that is continuously tested thanks to Travis CI, see the compatibility matrix).
If you're the owner of a library that strongly depends on Carbon, we recommend you to run unit tests daily requiring
"nesbot/carbon": "dev-master" (for ^2) or "nesbot/carbon": "dev-version-1.next" (for ^1), this way you can
detect incompatibilities earlier and report it to us before we tag a release. We'll pay attention and try to fix it to
make update to next minor releases as soft as possible.
We reserve the right to publish emergency patches within 24 hours after a release if a tag that does not respect this pattern would have been released despite our vigilance. In this very rare and particular case, we would mark the tag as broken on GitHub and backward compatibility would be based on previous stable tag.
Last, you must understand that Carbon extends PHP natives classes, that means Carbon can be impacted by any change that occurs in the date/time API of PHP. We watch new PHP versions and handle those changes as quickly as possible when detected, but as PHP does not follow the semantic versioning pattern, it basically means any releases (including patches) can have unexpected consequences on Carbon methods results.
Long term support
To benefit the better support, require Carbon using major version range (^1 or ^2). By requiring 1.26.*,
~1.26.0 or limited range such as >=1.20 <1.33, you fall to low priority support (only security and critical issues
will be fixed), our prior support goes to next minor releases of each major version. It applies to bug fixes and
low-cost features. Other new features will only be added in the last stable release. At the opposite, we recommend you
to restrain to a major number, as there is no compatibility guarantee from a major version to the next. It means
requiring >=2, as it allows any newer version, will probably leads to errors on releasing our next major version.
Open milestones can be patched if a minor bug is detected while if you're on a closed milestone, we'll more likely ask you to update first to an open one. See currently open milestones: