1 | 1 |
deleted file mode 100644 |
... | ... |
@@ -1,154 +0,0 @@ |
1 |
-# Contributing to Carbon |
|
2 |
- |
|
3 |
-## Issue Contributions |
|
4 |
- |
|
5 |
-Please report any security issue using [Tidelift security contact](https://tidelift.com/security). |
|
6 |
-Tidelift will coordinate the fix and disclosure. |
|
7 |
-Please don't disclose security bugs publicly until they have been handled by us. |
|
8 |
- |
|
9 |
-For any other bug or issue, please click this link and follow the template: |
|
10 |
-[Create new issue](https://github.com/briannesbitt/Carbon/issues/new) |
|
11 |
- |
|
12 |
-You may think this template does not apply to your case but please think again. A long description will never be as |
|
13 |
-clear as a code chunk with the output you expect from it (for either bug report or new features). |
|
14 |
- |
|
15 |
-## Code Contributions |
|
16 |
- |
|
17 |
-### Where to begin |
|
18 |
- |
|
19 |
-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: |
|
20 |
- |
|
21 |
-https://github.com/briannesbitt/Carbon/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22 |
|
22 |
- |
|
23 |
-Else, check the roadmap to see what we plan to do in next releases: |
|
24 |
- |
|
25 |
-https://github.com/briannesbitt/Carbon/issues/1681 |
|
26 |
- |
|
27 |
-### Develop locally, then submit changes |
|
28 |
- |
|
29 |
-Fork the [GitHub project](https://github.com/briannesbitt/Carbon) and download it locally: |
|
30 |
- |
|
31 |
-```shell |
|
32 |
-git clone https://github.com/<username>/Carbon.git |
|
33 |
-cd Carbon |
|
34 |
-git remote add upstream https://github.com/briannesbitt/Carbon.git |
|
35 |
-``` |
|
36 |
-Replace `<username>` with your GitHub username. |
|
37 |
- |
|
38 |
-Then, you can work on the master or create a specific branch for your development: |
|
39 |
- |
|
40 |
-```shell |
|
41 |
-git checkout -b my-feature-branch -t origin/master |
|
42 |
-``` |
|
43 |
- |
|
44 |
-You can now edit the "Carbon" directory contents. |
|
45 |
- |
|
46 |
-Before committing, please set your name and your e-mail (use the same e-mail address as in your GitHub account): |
|
47 |
- |
|
48 |
-```shell |
|
49 |
-git config --global user.name "Your Name" |
|
50 |
-git config --global user.email "your.email.address@example.com" |
|
51 |
-``` |
|
52 |
- |
|
53 |
-The ```--global``` argument will apply this setting for all your git repositories, remove it to set only your Carbon |
|
54 |
-fork with those settings. |
|
55 |
- |
|
56 |
-Now you can commit your modifications as you usually do with git: |
|
57 |
- |
|
58 |
-```shell |
|
59 |
-git add --all |
|
60 |
-git commit -m "The commit message log" |
|
61 |
-``` |
|
62 |
- |
|
63 |
-If your patch fixes an open issue, please insert ```#``` immediately followed by the issue number: |
|
64 |
- |
|
65 |
-```shell |
|
66 |
-git commit -m "#21 Fix this or that" |
|
67 |
-``` |
|
68 |
- |
|
69 |
-Use git rebase (not git merge) to sync your work from time to time: |
|
70 |
- |
|
71 |
-```shell |
|
72 |
-git fetch origin |
|
73 |
-git rebase origin/master |
|
74 |
-``` |
|
75 |
- |
|
76 |
-Please add some tests for bug fixes and features (so it will ensure next developments will not break your code), |
|
77 |
-then check all is right with phpunit: |
|
78 |
- |
|
79 |
-Install PHP if you haven't yet, then install composer: |
|
80 |
-https://getcomposer.org/download/ |
|
81 |
- |
|
82 |
-Update dependencies: |
|
83 |
-``` |
|
84 |
-./composer.phar update |
|
85 |
-``` |
|
86 |
- |
|
87 |
-Or if you installed composer globally: |
|
88 |
-``` |
|
89 |
-composer update |
|
90 |
-``` |
|
91 |
- |
|
92 |
-Then call phpunit: |
|
93 |
-``` |
|
94 |
-./vendor/bin/phpunit |
|
95 |
-``` |
|
96 |
- |
|
97 |
-Make sure all tests succeed before submitting your pull-request, else we will not be able to merge it. |
|
98 |
- |
|
99 |
-Push your work on your remote GitHub fork with: |
|
100 |
-``` |
|
101 |
-git push origin my-feature-branch |
|
102 |
-``` |
|
103 |
- |
|
104 |
-Go to https://github.com/yourusername/Carbon and select your feature branch. Click the 'Pull Request' button and fill |
|
105 |
-out the form. |
|
106 |
- |
|
107 |
-We will review it within a few days. And we thank you in advance for your help. |
|
108 |
- |
|
109 |
-## Versioning |
|
110 |
- |
|
111 |
-### Note about Semantic Versioning and breaking changes |
|
112 |
- |
|
113 |
-As a developer, you must understand every change is a breaking change. What is a bug for someone |
|
114 |
-is expected in someone else's workflow. The consequence of a change strongly depends on the usage. |
|
115 |
-[Semantic Versioning](https://semver.org/) relies to public API. In PHP, the public API of a class is its public |
|
116 |
-methods. However, if you extend a class, you can access protected methods, then if you use reflexion, you can |
|
117 |
-access private methods. So anything can become a public API if you force it to be. That doesn't mean we should handle |
|
118 |
-any possible usage, else we would have to publish a major release for each change and it would no longer make sense. |
|
119 |
- |
|
120 |
-So before any complain about a breaking change, be warned, we do not guarantee a strict Semantic Versioning as you |
|
121 |
-may expect, we're following a pragmatic interpretation of Semantic Versioning that allows the software to evolve in a |
|
122 |
-reliable way with reasonable maintenance effort. |
|
123 |
- |
|
124 |
-Concretely, we consider a change as breaking if it makes fail one of our unit test. We will do our best to avoid |
|
125 |
-incompatibilities with libraries that extends Carbon classes (such as Laravel that is continuously tested thanks to |
|
126 |
-Travis CI, [see the compatibility matrix](https://github.com/kylekatarnls/carbon-laravel/tree/master#carbon-1-dev-version-1next)). |
|
127 |
- |
|
128 |
-If you're the owner of a library that strongly depends on Carbon, we recommend you to run unit tests daily requiring |
|
129 |
-`"nesbot/carbon": "dev-master"` (for `^2`) or `"nesbot/carbon": "dev-version-1.next"` (for `^1`), this way you can |
|
130 |
-detect incompatibilities earlier and report it to us before we tag a release. We'll pay attention and try to fix it to |
|
131 |
-make update to next minor releases as soft as possible. |
|
132 |
- |
|
133 |
-We reserve the right to publish emergency patches within 24 hours after a release if a tag that does not respect |
|
134 |
-this pattern would have been released despite our vigilance. In this very rare and particular case, we would mark the |
|
135 |
-tag as broken on GitHub and backward compatibility would be based on previous stable tag. |
|
136 |
- |
|
137 |
-Last, you must understand that Carbon extends PHP natives classes, that means Carbon can be impacted by any change |
|
138 |
-that occurs in the date/time API of PHP. We watch new PHP versions and handle those changes as quickly as possible |
|
139 |
-when detected, but as PHP does not follow the semantic versioning pattern, it basically means any releases (including |
|
140 |
-patches) can have unexpected consequences on Carbon methods results. |
|
141 |
- |
|
142 |
-### Long term support |
|
143 |
- |
|
144 |
-To benefit the better support, require Carbon using major version range (`^1` or `^2`). By requiring `1.26.*`, |
|
145 |
-`~1.26.0` or limited range such as `>=1.20 <1.33`, you fall to low priority support (only security and critical issues |
|
146 |
-will be fixed), our prior support goes to next minor releases of each major version. It applies to bug fixes and |
|
147 |
-low-cost features. Other new features will only be added in the last stable release. At the opposite, we recommend you |
|
148 |
-to restrain to a major number, as there is no compatibility guarantee from a major version to the next. It means |
|
149 |
-requiring `>=2`, as it allows any newer version, will probably leads to errors on releasing our next major version. |
|
150 |
- |
|
151 |
-Open milestones can be patched if a minor bug is detected while if you're on a closed milestone, we'll more likely |
|
152 |
-ask you to update first to an open one. See currently open milestones: |
|
153 |
- |
|
154 |
-https://github.com/briannesbitt/Carbon/milestones |
1 | 1 |
new file mode 100644 |
... | ... |
@@ -0,0 +1,154 @@ |
1 |
+# Contributing to Carbon |
|
2 |
+ |
|
3 |
+## Issue Contributions |
|
4 |
+ |
|
5 |
+Please report any security issue using [Tidelift security contact](https://tidelift.com/security). |
|
6 |
+Tidelift will coordinate the fix and disclosure. |
|
7 |
+Please don't disclose security bugs publicly until they have been handled by us. |
|
8 |
+ |
|
9 |
+For any other bug or issue, please click this link and follow the template: |
|
10 |
+[Create new issue](https://github.com/briannesbitt/Carbon/issues/new) |
|
11 |
+ |
|
12 |
+You may think this template does not apply to your case but please think again. A long description will never be as |
|
13 |
+clear as a code chunk with the output you expect from it (for either bug report or new features). |
|
14 |
+ |
|
15 |
+## Code Contributions |
|
16 |
+ |
|
17 |
+### Where to begin |
|
18 |
+ |
|
19 |
+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: |
|
20 |
+ |
|
21 |
+https://github.com/briannesbitt/Carbon/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22 |
|
22 |
+ |
|
23 |
+Else, check the roadmap to see what we plan to do in next releases: |
|
24 |
+ |
|
25 |
+https://github.com/briannesbitt/Carbon/issues/1681 |
|
26 |
+ |
|
27 |
+### Develop locally, then submit changes |
|
28 |
+ |
|
29 |
+Fork the [GitHub project](https://github.com/briannesbitt/Carbon) and download it locally: |
|
30 |
+ |
|
31 |
+```shell |
|
32 |
+git clone https://github.com/<username>/Carbon.git |
|
33 |
+cd Carbon |
|
34 |
+git remote add upstream https://github.com/briannesbitt/Carbon.git |
|
35 |
+``` |
|
36 |
+Replace `<username>` with your GitHub username. |
|
37 |
+ |
|
38 |
+Then, you can work on the master or create a specific branch for your development: |
|
39 |
+ |
|
40 |
+```shell |
|
41 |
+git checkout -b my-feature-branch -t origin/master |
|
42 |
+``` |
|
43 |
+ |
|
44 |
+You can now edit the "Carbon" directory contents. |
|
45 |
+ |
|
46 |
+Before committing, please set your name and your e-mail (use the same e-mail address as in your GitHub account): |
|
47 |
+ |
|
48 |
+```shell |
|
49 |
+git config --global user.name "Your Name" |
|
50 |
+git config --global user.email "your.email.address@example.com" |
|
51 |
+``` |
|
52 |
+ |
|
53 |
+The ```--global``` argument will apply this setting for all your git repositories, remove it to set only your Carbon |
|
54 |
+fork with those settings. |
|
55 |
+ |
|
56 |
+Now you can commit your modifications as you usually do with git: |
|
57 |
+ |
|
58 |
+```shell |
|
59 |
+git add --all |
|
60 |
+git commit -m "The commit message log" |
|
61 |
+``` |
|
62 |
+ |
|
63 |
+If your patch fixes an open issue, please insert ```#``` immediately followed by the issue number: |
|
64 |
+ |
|
65 |
+```shell |
|
66 |
+git commit -m "#21 Fix this or that" |
|
67 |
+``` |
|
68 |
+ |
|
69 |
+Use git rebase (not git merge) to sync your work from time to time: |
|
70 |
+ |
|
71 |
+```shell |
|
72 |
+git fetch origin |
|
73 |
+git rebase origin/master |
|
74 |
+``` |
|
75 |
+ |
|
76 |
+Please add some tests for bug fixes and features (so it will ensure next developments will not break your code), |
|
77 |
+then check all is right with phpunit: |
|
78 |
+ |
|
79 |
+Install PHP if you haven't yet, then install composer: |
|
80 |
+https://getcomposer.org/download/ |
|
81 |
+ |
|
82 |
+Update dependencies: |
|
83 |
+``` |
|
84 |
+./composer.phar update |
|
85 |
+``` |
|
86 |
+ |
|
87 |
+Or if you installed composer globally: |
|
88 |
+``` |
|
89 |
+composer update |
|
90 |
+``` |
|
91 |
+ |
|
92 |
+Then call phpunit: |
|
93 |
+``` |
|
94 |
+./vendor/bin/phpunit |
|
95 |
+``` |
|
96 |
+ |
|
97 |
+Make sure all tests succeed before submitting your pull-request, else we will not be able to merge it. |
|
98 |
+ |
|
99 |
+Push your work on your remote GitHub fork with: |
|
100 |
+``` |
|
101 |
+git push origin my-feature-branch |
|
102 |
+``` |
|
103 |
+ |
|
104 |
+Go to https://github.com/yourusername/Carbon and select your feature branch. Click the 'Pull Request' button and fill |
|
105 |
+out the form. |
|
106 |
+ |
|
107 |
+We will review it within a few days. And we thank you in advance for your help. |
|
108 |
+ |
|
109 |
+## Versioning |
|
110 |
+ |
|
111 |
+### Note about Semantic Versioning and breaking changes |
|
112 |
+ |
|
113 |
+As a developer, you must understand every change is a breaking change. What is a bug for someone |
|
114 |
+is expected in someone else's workflow. The consequence of a change strongly depends on the usage. |
|
115 |
+[Semantic Versioning](https://semver.org/) relies to public API. In PHP, the public API of a class is its public |
|
116 |
+methods. However, if you extend a class, you can access protected methods, then if you use reflexion, you can |
|
117 |
+access private methods. So anything can become a public API if you force it to be. That doesn't mean we should handle |
|
118 |
+any possible usage, else we would have to publish a major release for each change and it would no longer make sense. |
|
119 |
+ |
|
120 |
+So before any complain about a breaking change, be warned, we do not guarantee a strict Semantic Versioning as you |
|
121 |
+may expect, we're following a pragmatic interpretation of Semantic Versioning that allows the software to evolve in a |
|
122 |
+reliable way with reasonable maintenance effort. |
|
123 |
+ |
|
124 |
+Concretely, we consider a change as breaking if it makes fail one of our unit test. We will do our best to avoid |
|
125 |
+incompatibilities with libraries that extends Carbon classes (such as Laravel that is continuously tested thanks to |
|
126 |
+Travis CI, [see the compatibility matrix](https://github.com/kylekatarnls/carbon-laravel/tree/master#carbon-1-dev-version-1next)). |
|
127 |
+ |
|
128 |
+If you're the owner of a library that strongly depends on Carbon, we recommend you to run unit tests daily requiring |
|
129 |
+`"nesbot/carbon": "dev-master"` (for `^2`) or `"nesbot/carbon": "dev-version-1.next"` (for `^1`), this way you can |
|
130 |
+detect incompatibilities earlier and report it to us before we tag a release. We'll pay attention and try to fix it to |
|
131 |
+make update to next minor releases as soft as possible. |
|
132 |
+ |
|
133 |
+We reserve the right to publish emergency patches within 24 hours after a release if a tag that does not respect |
|
134 |
+this pattern would have been released despite our vigilance. In this very rare and particular case, we would mark the |
|
135 |
+tag as broken on GitHub and backward compatibility would be based on previous stable tag. |
|
136 |
+ |
|
137 |
+Last, you must understand that Carbon extends PHP natives classes, that means Carbon can be impacted by any change |
|
138 |
+that occurs in the date/time API of PHP. We watch new PHP versions and handle those changes as quickly as possible |
|
139 |
+when detected, but as PHP does not follow the semantic versioning pattern, it basically means any releases (including |
|
140 |
+patches) can have unexpected consequences on Carbon methods results. |
|
141 |
+ |
|
142 |
+### Long term support |
|
143 |
+ |
|
144 |
+To benefit the better support, require Carbon using major version range (`^1` or `^2`). By requiring `1.26.*`, |
|
145 |
+`~1.26.0` or limited range such as `>=1.20 <1.33`, you fall to low priority support (only security and critical issues |
|
146 |
+will be fixed), our prior support goes to next minor releases of each major version. It applies to bug fixes and |
|
147 |
+low-cost features. Other new features will only be added in the last stable release. At the opposite, we recommend you |
|
148 |
+to restrain to a major number, as there is no compatibility guarantee from a major version to the next. It means |
|
149 |
+requiring `>=2`, as it allows any newer version, will probably leads to errors on releasing our next major version. |
|
150 |
+ |
|
151 |
+Open milestones can be patched if a minor bug is detected while if you're on a closed milestone, we'll more likely |
|
152 |
+ask you to update first to an open one. See currently open milestones: |
|
153 |
+ |
|
154 |
+https://github.com/briannesbitt/Carbon/milestones |