mirror of
https://github.com/ramsey/uuid.git
synced 2026-06-14 15:56:48 +03:00
Ben Ramsey
6d712900f4
The ramsey/uuid library has requirements to run on 32-bit and 64-bit systems, as well as little-endian and big-endian systems. Travis CI only provides hardware for testing 64-bit, little-endian CPU architectures, but they recently announced support for Docker[^1]. After some research, I found it is possible to use [QEMU][] with [chroot][] jails on Travis CI to emulate other CPU architectures and run tests through these chroot jails[^2]. Unfortunately, it takes an awful long time to set up a chroot jail, build PHP within it, and run the tests. It wasn't reasonable to expect to do this on every single push to the ramsey/uuid repository. This is where Docker comes in. I was able to create chroot jails for each architecture and version of PHP combination I need to test and then turn these into Docker images, which Travis is able to download and run fairly quickly. The instances on which Travis CI is running their Docker services do not currently support phpenv or php-build, so I needed to masquerade as a Python project and specify all PHP versions and CPU architectures in environment variables in my `.travis.yml` configuration. I run `composer install` and report to Coveralls outside of the Docker images, but all tests are run within the Docker images. The Docker image I created for PHP 7.0.0RC4 on MIPS architecture produces segfaults when attempting to build PHP with Phar. PHP builds okay without Phar, but then it produces segfaults when running any PHP script on the image, so I'm leaving out 7.0.0RC4 on MIPS for now. The Docker images for use with ramsey/uuid tests are available here: <https://hub.docker.com/r/benramsey/ramsey-uuid/>. [^1]: "Using Docker on Travis CI," <http://blog.travis-ci.com/2015-08-19-using-docker-on-travis-ci/> [^2]: "Running Travis CI tests on ARM architecture," <https://www.tomaz.me/2013/12/02/running-travis-ci-tests-on-arm.html> [qemu]: http://wiki.qemu.org/Main_Page [chroot]: https://en.wikipedia.org/wiki/Chroot
79 lines
4.4 KiB
Markdown
79 lines
4.4 KiB
Markdown
# Contributing
|
|
|
|
Contributions are welcome. We accept pull requests on [GitHub](https://github.com/ramsey/uuid).
|
|
|
|
This project adheres to a [Contributor Code of Conduct](https://github.com/ramsey/uuid/blob/master/CONDUCT.md). By participating in this project and its community, you are expected to uphold this code.
|
|
|
|
## Team members
|
|
|
|
* [Ben Ramsey](https://github.com/ramsey) - original author and maintainer
|
|
* [Marijn Huizendveld](https://github.com/marijn) - contributor, author of UUID type definition for Doctrine DBAL
|
|
* [Thibaud Fabre](https://github.com/aztech-dev) - contributor, lead developer for version 3.0.0 re-architecture
|
|
|
|
## Communication Channels
|
|
|
|
You can find help and discussion in the following places:
|
|
|
|
* Gitter chat: <https://gitter.im/ramsey/uuid>
|
|
* GitHub Issues: <https://github.com/ramsey/uuid/issues>
|
|
* Wiki: <https://github.com/ramsey/uuid/wiki>
|
|
|
|
## Reporting Bugs
|
|
|
|
Bugs are tracked in our project's [issue tracker](https://github.com/ramsey/uuid/issues).
|
|
|
|
When submitting a bug report, please include enough information for us to reproduce the bug. A good bug report includes the following sections:
|
|
|
|
* Expected outcome
|
|
* Actual outcome
|
|
* Steps to reproduce, including sample code
|
|
* Any other information that will help us debug and reproduce the issue, including stack traces, system/environment information, and screenshots
|
|
|
|
**Please do not include passwords or any personally identifiable information in your bug report and sample code.**
|
|
|
|
## Fixing Bugs
|
|
|
|
We welcome pull requests to fix bugs!
|
|
|
|
If you see a bug report that you'd like to fix, please feel free to do so. Following the directions and guidelines described in the "Adding New Features" section below, you may create bugfix branches and send us pull requests.
|
|
|
|
## Adding New Features
|
|
|
|
If you have an idea for a new feature, it's a good idea to check out our [issues](https://github.com/ramsey/uuid/issues) or active [pull requests](https://github.com/ramsey/uuid/pulls) first to see if the feature is already being worked on. If not, feel free to submit an issue first, asking whether the feature is beneficial to the project. This will save you from doing a lot of development work only to have your feature rejected. We don't enjoy rejecting your hard work, but some features just don't fit with the goals of the project.
|
|
|
|
When you do begin working on your feature, here are some guidelines to consider:
|
|
|
|
* Your pull request description should clearly detail the changes you have made. We will use this description to add to our CHANGELOG. If there is no description or it does not adequately describe your feature, we will ask you to update the description.
|
|
* We following the **[PSR-2 coding standard](http://www.php-fig.org/psr/psr-2/)**. Please ensure your code does, too.
|
|
* Please **write tests** for any new features you add.
|
|
* Please **ensure that tests pass** before submitting your pull request. We have Travis CI automatically running tests for pull requests. However, running the tests locally will help save time.
|
|
* **Use topic/feature branches.** Please do not ask us to pull from your master branch.
|
|
* **Submit one feature per pull request.** If you have multiple features you wish to submit, please break them up into separate pull requests.
|
|
* **Send coherent history**. Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please squash them before submitting.
|
|
|
|
## Running Tests
|
|
|
|
The following tests must pass before we will accept a pull request. If any of these do not pass, it will result in a complete build failure. Before you can run these, be sure to `composer install`.
|
|
|
|
```
|
|
./vendor/bin/parallel-lint src tests
|
|
./vendor/bin/phpunit --verbose
|
|
./vendor/bin/phpcs src --standard=psr2 -sp
|
|
```
|
|
|
|
### Locally Test With Emulated MIPS Architecture
|
|
|
|
The following commands use [Vagrant](https://www.vagrantup.com/) to start an Ubuntu VM, install necessary dependencies, and then run the `util/run-tests.sh` script that will download a Docker image emulating the MIPS architecture. This is especially helpful for testing UUID generation in a big-endian environment.
|
|
|
|
```
|
|
vagrant init ubuntu/trusty64
|
|
vagrant up
|
|
vagrant ssh
|
|
sudo apt-get install docker.io qemu-user-static php5-cli php5-curl
|
|
cd /vagrant
|
|
curl -sS https://getcomposer.org/installer | php
|
|
php composer.phar install --no-interaction --prefer-dist
|
|
mkdir -p build/logs
|
|
ARCH=mips PHP_VERSION=5.6.14 TRAVIS_BUILD_DIR=/vagrant ./util/run-tests.sh
|
|
```
|