Skip to content

Commit 55e2a31

Browse files
committed
Add contribution and release process docs
1 parent 20ddb9c commit 55e2a31

File tree

1 file changed

+145
-0
lines changed

1 file changed

+145
-0
lines changed

CONTRIBUTING.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Contributing to the PHP Library for MongoDB
2+
3+
## Initializing the Repository
4+
5+
Developers who would like to contribute to the library will need to clone it and
6+
initialize the project dependencies with [Composer](https://getcomposer.org/):
7+
8+
```
9+
$ git clone https://github.com/mongodb/mongo-php-library.git
10+
$ cd mongo-php-library
11+
$ composer update
12+
```
13+
14+
In addition to installing project dependencies, Composer will check that the
15+
required extension version is installed. Directions for installing the extension
16+
may be found [here](http://php.net/manual/en/mongodb.installation.php).
17+
18+
Installation directions for Composer may be found in its
19+
[Getting Started](https://getcomposer.org/doc/00-intro.md) guide.
20+
21+
## Testing
22+
23+
The library's test suite uses [PHPUnit](https://phpunit.de/), which should be
24+
installed as a development dependency by Composer.
25+
26+
The test suite may be executed with:
27+
28+
```
29+
$ vendor/bin/phpunit
30+
```
31+
32+
The `phpunit.xml.dist` file is used as the default configuration file for the
33+
test suite. In addition to various PHPUnit options, it defines required
34+
`MONGODB_URI` and `MONGODB_DATABASE` environment variables. You may customize
35+
this configuration by creating your own `phpunit.xml` file based on the
36+
`phpunit.xml.dist` file we provide.
37+
38+
### Testing on HHVM
39+
40+
By default, the PHPUnit script relies on the `php` interpreter for your shell
41+
(i.e. `#!/usr/bin/env php`). You can run the test suite with HHVM like so:
42+
43+
```
44+
$ hhvm vendor/bin/phpunit
45+
```
46+
47+
## Releasing
48+
49+
The follow steps outline the release process for a maintenance branch (e.g.
50+
releasing the `vX.Y` branch as X.Y.Z).
51+
52+
### Ensure PHP version compatibility
53+
54+
Ensure that the library test suite completes on supported versions of PHP and
55+
HHVM.
56+
57+
### Transition JIRA issues and version
58+
59+
Update the fix version field for all resolved issues with the corresponding ".x"
60+
fix version.
61+
62+
Update the version's release date and status from the
63+
[Manage Versions](https://jira.mongodb.org/plugins/servlet/project-config/PHPLIB/versions)
64+
page.
65+
66+
Transition all resolved issues for this version to the closed state. If changing
67+
the issues in bulk, be sure to allow email notifications.
68+
69+
### Update version info
70+
71+
The PHP library uses [semantic versioning](http://semver.org/). Do not break
72+
backwards compatibility in a non-major release or your users will kill you.
73+
74+
A version constant may be added at a later date (see:
75+
[PHPLIB-131](https://jira.mongodb.org/browse/PHPLIB-131)). For now, there is
76+
nothing to update.
77+
78+
### Tag release
79+
80+
The maintenance branch's HEAD will be the target for our release tag:
81+
82+
```
83+
$ git tag -a -m "Release X.Y.Z" X.Y.Z
84+
```
85+
86+
### Push tags
87+
88+
```
89+
$ git push --tags
90+
```
91+
92+
### Publish release notes
93+
94+
The following template should be used for creating GitHub release notes via
95+
[this form](https://github.com/mongodb/mongo-php-library/releases/new).
96+
97+
```
98+
The PHP team is happy to announce that version X.Y.Z of our MongoDB PHP library is now available. This library is a high-level abstraction for the PHP 5, PHP 7, and HHVM drivers (i.e. [`mongodb`](http://php.net/mongodb) extension).
99+
100+
**Release Highlights**
101+
102+
<one or more paragraphs describing important changes in this release>
103+
104+
A complete list of resolved issues in this release may be found at:
105+
$JIRA_URL
106+
107+
**Documentation**
108+
109+
Documentation for this library may be found at:
110+
https://docs.mongodb.com/php-library/
111+
112+
**Feedback**
113+
114+
If you encounter any bugs or issues with this library, please report them via this form:
115+
https://jira.mongodb.org/secure/CreateIssue.jspa?pid=12483&issuetype=1
116+
117+
**Installation**
118+
119+
This library may be installed or upgraded with:
120+
121+
composer require "mongodb/mongodb=^1.0.0"
122+
123+
Installation instructions for the PHP and HHVM driver may be found in the [PHP.net documentation](http://php.net/manual/en/mongodb.installation.php).
124+
```
125+
126+
The URL for the list of resolved JIRA issues will need to be updated with each
127+
release. You may obtain the list from
128+
[this form](https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=12483).
129+
130+
If commits from community contributors were included in this release, append the
131+
following section:
132+
133+
```
134+
**Thanks**
135+
136+
Thanks for our community contributors for this release:
137+
138+
* [$CONTRIBUTOR_NAME](https://github.com/$GITHUB_USERNAME)
139+
```
140+
141+
Release announcements should also be sent to the `mongodb-user@googlegroups.com`
142+
and `mongodb-announce@googlegroups.com` mailing lists.
143+
144+
Consider announcing each release on Twitter. Significant releases should also be
145+
announced via [@MongoDB](http://twitter.com/mongodb) as well.

0 commit comments

Comments
 (0)