Skip to content

Commit

Permalink
Working on contribution guide and update notes.
Browse files Browse the repository at this point in the history
  • Loading branch information
@taylorotwell
taylorotwell committed Jan 5, 2015
1 parent ba9e9d2 commit 88862cd
Show file tree
Hide file tree
Showing 2 changed files with 6 additions and 137 deletions.
98 changes: 5 additions & 93 deletions contributions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,6 @@

- [Introduction](#introduction)
- [Core Development Discussion](#core-development-discussion)
- [New Features](#new-features)
- [Bugs](#bugs)
- [Creating Liferaft Applications](#creating-liferaft-applications)
- [Grabbing Liferaft Applications](#grabbing-liferaft-applications)
- [Which Branch?](#which-branch)
- [Security Vulnerabilities](#security-vulnerabilities)
- [Coding Style](#coding-style)
Expand All @@ -15,7 +11,11 @@

Laravel is an open-source project and anyone may contribute to Laravel for its improvement. We welcome contributors, regardless of skill level, gender, race, religion, or nationality. Having a diverse, vibrant community is one of the core values of the framework!

To encourage active collaboration, Laravel currently only accepts pull requests, not bug reports. "Bug reports" may be sent in the form of a pull request containing a failing unit test. Alternatively, a demonstration of the bug within a sandbox Laravel application may be sent as a pull request to the [main Laravel repository](https://github.com/laravel/laravel). A failing unit test or sandbox application provides the development team "proof" that the bug exists, and, after the development team addresses the bug, serves as a reliable indicator that the bug remains fixed.
To encourage active collaboration, Laravel strongly encourages pull requests, not just bug reports. "Bug reports" may also be sent in the form of a pull request containing a failing unit test.

Your issue report should contain a title and a clear description of the issue. You should also include as much relevant information as possible and a code sample that demonstrates the issue. The goal of a bug report is to make it easy for yourself - and others - to replicate the bug and develop a fix.

Remember, issues reports are created in the hope that others with the same problem will be able to collaborate with you on solving it. Do not expect that the issue report will automatically see any activity or that others will jump to fix it. Creating an issue serves to help yourself and others start on the path of fixing the problem.

The Laravel source code is managed on Github, and there are repositories for each of the Laravel projects:

Expand All @@ -36,97 +36,9 @@ Discussion regarding bugs, new features, and implementation of existing features

The `#laravel-dev` IRC channel is open to all. All are welcome to join the channel either to participate or simply observe the discussions!

<a name="new-features"></a>
## New Features

Before sending pull requests for new features, please contact Taylor Otwell via the `#laravel-dev` IRC channel (Freenode). If the feature is found to be a good fit for the framework, you are free to make a pull request. If the feature is rejected, don't give up! You are still free to turn your feature into a package which can be released to the world via [Packagist](https://packagist.org/).

When adding new features, don't forget to add unit tests! Unit tests help ensure the stability and reliability of the framework as new features are added.

<a name="bugs"></a>
## Bugs

### Via Unit Test

Pull requests for bugs may be sent without prior discussion with the Laravel development team. When submitting a bug fix, try to include a unit test that ensures the bug never appears again!

If you believe you have found a bug in the framework, but are unsure how to fix it, please send a pull request containing a failing unit test. A failing unit test provides the development team "proof" that the bug exists, and, after the development team addresses the bug, serves as a reliable indicator that the bug remains fixed.

If are unsure how to write a failing unit test for a bug, review the other unit tests included with the framework. If you're still lost, you may ask for help in the `#laravel` IRC channel (Freenode).

### Via Laravel Liferaft

If you aren't able to write a unit test for your issue, Laravel Liferaft allows you to create a demo application that recreates the issue. Liferaft can even automate the forking and sending of pull requests to the Laravel repository. Once your Liferaft application is submitted, a Laravel maintainer can run your application on [Homestead](/docs/homestead) and review your issue.

<a name="creating-liferaft-applications"></a>
## Creating Liferaft Applications

Laravel Liferaft provides a fresh, innovative way to contribute to Laravel. First, you will need to install the Liferaft CLI tool via Composer:

### Installing Liferaft

composer global require "laravel/liferaft=~1.0"

Make sure to place the `~/.composer/vendor/bin` directory in your PATH so the `liferaft` executable is found when you run the `liferaft` command in your terminal.

### Authenticating With GitHub

Before getting started with Liferaft, you need to register a GitHub personal access token. You can generate a personal access token from your [GitHub settings panel](https://github.com/settings/applications). The default scopes selected by GitHub will be sufficient; however, if you wish, you may grant the `delete_repo` scope so Liferaft can delete your old sandbox applications.

liferaft auth my-github-token

### Create A New Liferaft Application

To create a new Liferaft application, just use the `new` command:

liferaft new my-bug-fix

This command will do several things. First, it will fork the [Laravel GitHub repository](https://github.com/laravel/laravel) to your GitHub account. Next, it will clone the forked repository to your machine and install the Composer dependencies. Once the repository has been installed, you can begin recreating your issue within the Liferaft application!

### Recreating Your Issue

After creating a Liferaft application, simply recreate your issue. You are free to define routes, create Eloquent models, and even create database migrations! The only requirement is that your application is able to run on a fresh [Laravel Homestead](/docs/homestead) virtual machine. This allows Laravel maintainers to easily run your application on their own machines.

Once you have recreated your issue within the Liferaft application, you're ready to send it back to the Laravel repository for review!

### Send Your Application For Review

Once you have recreated your issue, it's almost time to send it for review! However, you should first complete the `liferaft.md` file that was generated in your Liferaft application. The first line of this file will be the title of your pull request. The remaining content will be included in the pull request body. Of course, GitHub Flavored Markdown is supported.

After completing the `liferaft.md` file, push all of your changes to your GitHub repository. Next, just run the Liferaft `throw` command from your application's directory:

liferaft throw

This command will create a pull request against the Laravel GitHub repository. A Laravel maintainer can easily grab your application and run it in their own Homestead environment!

<a name="grabbing-liferaft-applications"></a>
## Grabbing Liferaft Applications

Intrested in contributing to Laravel? Liferaft makes it painless to install Liferaft applications and view them on your own [Homestead environment](/docs/homestead).

First, for convenience, clone the [laravel/laravel](https://github.com/laravel/laravel) into a `liferaft` directory on your machine:

git clone https://github.com/laravel/laravel.git liferaft

Next, check out the `develop` branch so you will be able to install Liferaft applications that target both stable and upcoming Laravel releases:

git checkout -b develop origin/develop

Next, you can run the Liferaft `grab` command from your repository directory. For example, if you want to install the Liferaft application associated with pull request #3000, you should run the following command:

liferaft grab 3000

The `grab` command will create a new branch on your Liferaft directory, and pull in the changes for the specified pull request. Once the Liferaft application is installed, simply serve the directory through your [Homestead](/docs/homestead) virtual machine! Once you debug the issue, don't forget to send a pull request to the [laravel/framework](https://github.com/laravel/framework) repository with the proper fix!

Have an extra hour and want to solve a random issue? Just run `grab` without a pull request ID:

liferaft grab

<a name="which-branch"></a>
## Which Branch?

> **Note:** This section primarly applies to those sending pull requests to the [laravel/framework](https://github.com/laravel/framework) repository, not Liferaft applications.
**All** bug fixes should be sent to the latest stable branch. Bug fixes should **never** be sent to the `master` branch unless they fix features that exist only in the upcoming release.

**Minor** features that are **fully backwards compatible** with the current Laravel release may be sent to the latest stable branch.
Expand Down
45 changes: 1 addition & 44 deletions upgrade.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,50 +9,7 @@
<a name="upgrade-5.0"></a>
## Upgrading To 5.0 From 4.2

### Quick Upgrade Using LegacyServiceProvider

Laravel 5.0 introduces a robust new folder structure. However, if you wish to upgrade your application to Laravel 5.0 while maintaining the Laravel 4.2 folder structure, you may use the `Illuminate\Foundation\Providers\LegacyStructureServiceProvider`. To upgrade to Laravel 5.0 using this provider, you should do the following:

**1.** Update your `composer.json` dependency on `laravel/framework` to `5.0.*`.

**2.** Run `composer update --no-scripts`.

**3.** Add the `Illuminate\Foundation\Providers\LegacyStructureServiceProvider` to your `providers` array in `app/config/app.php` file.

**4.** Remove the `Illuminate\Session\CommandsServiceProvider`, `Illuminate\Routing\ControllerServiceProvider`, and `Illuminate\Workbench\WorkbenchServiceProvider` entries from your `providers` array in the `app/config/app.php` file.

**5.** Add the following set of paths to the bottom of your `bootstrap/paths.php` file:

'commands' => __DIR__.'/../app/commands',
'config' => __DIR__.'/../app/config',
'controllers' => __DIR__.'/../app/controllers',
'database' => __DIR__.'/../app/database',
'filters' => __DIR__.'/../app/filters',
'lang' => __DIR__.'/../app/lang',
'providers' => __DIR__.'/../app/providers',
'requests' => __DIR__.'/../app/requests',

Once these changes have been made, you should be able to run your Laravel application like normal. However, you should continue reviewing the following upgrade notices.

### Compile Configuration File

The `app/config/compile.php` configuration file should now follow the following format:

<?php

return [

'files' => [
//
],

'providers' => [
//
],

];

The new `providers` option allows you to list service providers which return arrays of files from their `compiles` method.
Information coming soon.

### Beanstalk Queuing

Expand Down

0 comments on commit 88862cd

Please sign in to comment.