From 705aa3c9131b47135448485471485ee61bc642e0 Mon Sep 17 00:00:00 2001 From: Carsten Brandt Date: Thu, 7 May 2015 19:01:27 +0200 Subject: [PATCH] updated contribution guidelines fixes #7991 related to #7812 --- CONTRIBUTING.md | 3 +- README.md | 13 ++--- docs/internals/getting-started.md | 44 +--------------- docs/internals/git-workflow.md | 91 +++++++++++++++++++++++++++------- docs/internals/report-an-issue.md | 4 ++ docs/internals/translation-workflow.md | 4 +- 6 files changed, 86 insertions(+), 73 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d908ff0..0b086f6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,4 +3,5 @@ Contributing to Yii2 - [Report an issue](docs/internals/report-an-issue.md) - [Translate documentation or messages](docs/internals/translation-workflow.md) -- [Contribute to the core code or fix bugs](docs/internals/getting-started.md) +- [Give us feedback or start a design discussion](http://www.yiiframework.com/forum/index.php/forum/42-design-discussions-for-yii-20/) +- [Contribute to the core code or fix bugs](docs/internals/git-workflow.md) diff --git a/README.md b/README.md index eab1cb3..12e5baa 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ Yii 2.0 has a [Definitive Guide](http://www.yiiframework.com/doc-2.0/guide-index a [Class Reference](http://www.yiiframework.com/doc-2.0/index.html) which cover every detail of Yii. There is also a [PDF version](http://stuff.cebe.cc/yii2-guide.pdf) of the Definitive Guide -and a [Definitive Guide Mirror](http://stuff.cebe.cc/yii2docs/) which update every 15 minutes. +and a [Definitive Guide Mirror](http://stuff.cebe.cc/yii2docs/) which is updated every 15 minutes. For 1.1 users, you may refer to [Upgrading from Yii 1.1](docs/guide/intro-upgrade-from-v1.md) to have a general idea of what has changed in 2.0. @@ -55,11 +55,8 @@ HOW TO PARTICIPATE You may participate in the following ways: -* [Report issues](https://github.com/yiisoft/yii2/issues) -* [Give us feedback or start a design discussion](http://www.yiiframework.com/forum/index.php/forum/42-design-discussions-for-yii-20/) -* Fix issues, develop features, write/polish documentation - - Before you start, please adopt an existing issue (labelled with "ready for adoption") or start a new one to avoid duplicated efforts. - - Please submit a merge request after you finish development. - -In order to make it easier we've prepared [special `yii2-dev` Composer package](https://github.com/yiisoft/yii2/blob/master/docs/internals/getting-started.md). +- [Report an issue](docs/internals/report-an-issue.md) +- [Translate documentation or messages](docs/internals/translation-workflow.md) +- [Give us feedback or start a design discussion](http://www.yiiframework.com/forum/index.php/forum/42-design-discussions-for-yii-20/) +- [Contribute to the core code or fix bugs](docs/internals/git-workflow.md) diff --git a/docs/internals/getting-started.md b/docs/internals/getting-started.md index e024d42..33065da 100644 --- a/docs/internals/getting-started.md +++ b/docs/internals/getting-started.md @@ -1,46 +1,4 @@ Getting started with Yii2 development ===================================== -1. Clone your fork of yii2 `git clone git@github.com:/yii2.git`. -2. Change into the repo folder `cd yii2`. -3. run `./build/build dev/app basic` to clone the basic app and install composer dependencies for the basic app. - This command will install foreign composer packages as normal but will link the yii2 repo to - the currently checked out repo, so you have one instance of all the code installed. -4. Do the same for the advanced app if needed: `./build/build dev/app advanced` - This command will also be used to update dependencies, it runs `composer update` internally. -5. Now you have a working playground for hacking on Yii 2. - -You may also add the yii2 upstream repo to pull the latest changes: - -``` -git remote add upstream https://github.com/yiisoft/yii2.git -``` - -Please refer to [Git workflow for Yii 2 contributors](git-workflow.md) for details about creating pull requests. - -Unit tests ----------- - -To run the unit tests you have to install composer packages for the dev-repo. -Run `composer update` in the repo root directory to get the latest packages. - -You can now execute unit tests by running `phpunit`. - -You may limit the tests to a group of tests you are working on e.g. to run only tests for the validators and redis -`phpunit --group=validators,redis`. - -Extensions ----------- - -> Note: this section is outdated as we are currently changing the repository structure. instructions will be updated soon. - -To work on extensions you have to install them in the application you want to try them in. -Just add them to the `composer.json` as you would normally do e.g. add `"yiisoft/yii2-redis": "*"` to the -`require` section of the basic app. -Running `./build/build app/link basic` will install the extension and its dependecies and create -a symlink to `extensions/redis` so you are not working the composer vendor dir but the yii2 repo directly. - -Functional and acceptance tests for applications ------------------------------------------------- - -See `apps/advanced/tests/README.md` and `apps/basic/tests/README.md` to learn about how to run Codeception tests. +See [Git workflow for Yii 2 contributors](git-workflow.md) on how to set up your environment. diff --git a/docs/internals/git-workflow.md b/docs/internals/git-workflow.md index 675aa06..8e4f4ec 100644 --- a/docs/internals/git-workflow.md +++ b/docs/internals/git-workflow.md @@ -2,12 +2,17 @@ Git workflow for Yii 2 contributors =================================== So you want to contribute to Yii? Great! But to increase the chances of your changes being accepted quickly, please -follow the following steps (the first 2 steps only need to be done the first time you contribute). If you are new to git +follow the following steps. If you are new to git and github, you might want to first check out [github help](http://help.github.com/), [try git](https://try.github.com) or learn something about [git internal data model](http://nfarina.com/post/9868516270/git-is-simpler). -### 1. [Fork](http://help.github.com/fork-a-repo/) the Yii repository on github and clone your fork to your development -environment +Prepare your development environment +------------------------------------ + +The following steps will create a development environment for Yii, which you can use to work +on the core code of Yii framework. These steps only need to be done the first time you contribute. + +### 1. [Fork](http://help.github.com/fork-a-repo/) the Yii repository on github and clone your fork to your development environment ``` git clone git@github.com:YOUR-GITHUB-USERNAME/yii2.git @@ -24,18 +29,65 @@ Change to the directory where you cloned Yii, normally, "yii2". Then enter the f git remote add upstream git://github.com/yiisoft/yii2.git ``` -### 3. Make sure there is an issue created for the thing you are working on if it requires significant effort to fix +### 3. Prepare the testing environment + +The following steps are not necessary if you want to work only on translations or documentation. + +- run `composer update` to install dependencies (assuming you have [composer installed globally](https://getcomposer.org/doc/00-intro.md#globally)). +- run `php build/build dev/app basic` to clone the basic app and install composer dependencies for the basic app. + This command will install foreign composer packages as normal but will link the yii2 repo to + the currently checked out repo, so you have one instance of all the code installed. + + Do the same for the advanced app if needed: `php build/build dev/app advanced`. + + This command will also be used to update dependencies, it runs `composer update` internally. + +**Now you have a working playground for hacking on Yii 2.** + +The following steps are optional. + +### Unit tests + +You can execute unit tests by running `phpunit` in the repo root directory. If you do not have phpunit installed globally +you can run `php vendor/bin/phpunit` instead. + +Some tests require additional databases to be set up and configured. You can create `tests/data/config.local.php` to override +settings that are configured in `tests/data/config.php`. + +You may limit the tests to a group of tests you are working on e.g. to run only tests for the validators and redis +`phpunit --group=validators,redis`. You get the list of available groups by running `phpunit --groups`. + +### Extensions + +To work on extensions you have clone the extension repository. We have created a command that can do this for you: + + php build/build dev/ext + +where `` is the name of the extension, e.g. `redis`. + +If you want to test the extension in one of the application templates, just add them to the `composer.json` of the application as you would +normally do e.g. add `"yiisoft/yii2-redis": "*"` to the `require` section of the basic app. +Running `php build/build dev/app basic` will install the extension and its dependecies and create +a symlink to `extensions/redis` so you are not working in the composer vendor dir but in the yii2 repository directly. + + +Working on bugs and features +---------------------------- + +Having prepared your develop environment as explained above you can now start working on the feature or bugfix. + +### 1. Make sure there is an issue created for the thing you are working on if it requires significant effort to fix All new features and bug fixes should have an associated issue to provide a single point of reference for discussion and documentation. Take a few minutes to look through the existing issue list for one that matches the contribution you intend to make. If you find one already on the issue list, then please leave a comment on that issue indicating you -intend to work on that item. If you do not find an existing issue matching what you intend to work on, please open a -new issue for your item or create a pull request directly if it is straightforward fix. This will allow the team to review your suggestion, and provide appropriate feedback along -the way. +intend to work on that item. If you do not find an existing issue matching what you intend to work on, please +[open a new issue](report-an-issue.md) or create a pull request directly if it is straightforward fix. This will allow the team to +review your suggestion, and provide appropriate feedback along the way. > For small changes or documentation issues or straightforward fixes, you don't need to create an issue, a pull request is enough in this case. -### 4. Fetch the latest code from the main Yii branch +### 2. Fetch the latest code from the main Yii branch ``` git fetch upstream @@ -43,7 +95,7 @@ git fetch upstream You should start at this point for every new contribution to make sure you are working on the latest code. -### 5. Create a new branch for your feature based on the current Yii master branch +### 3. Create a new branch for your feature based on the current Yii master branch > That's very important since you will not be able to submit more than one pull request from your account if you'll use master. @@ -57,14 +109,14 @@ git checkout upstream/master git checkout -b 999-name-of-your-branch-goes-here ``` -### 6. Do your magic, write your code +### 4. Do your magic, write your code Make sure it works :) Unit tests are always welcome. Tested and well covered code greatly simplifies the task of checking your contributions. Failing unit tests as issue description are also accepted. -### 7. Update the CHANGELOG +### 5. Update the CHANGELOG Edit the CHANGELOG file to include your change, you should insert this at the top of the file under the "Work in progress" heading, the line in the change log should look like one of the following: @@ -79,7 +131,7 @@ The changelog should be grouped by type (`Bug`,`Enh`) and ordered by issue numbe For very small fixes, e.g. typos and documentation changes, there is no need to update the CHANGELOG. -### 8. Commit your changes +### 6. Commit your changes add the files/changes you want to commit to the [staging area](http://gitref.org/basic/#add) with @@ -96,7 +148,7 @@ automatically link your commit with the ticket: git commit -m "A brief description of this change which fixes #42 goes here" ``` -### 9. Pull the latest Yii code from upstream into your branch +### 7. Pull the latest Yii code from upstream into your branch ``` git pull upstream master @@ -106,31 +158,32 @@ This ensures you have the latest code in your branch before you open your pull r you should fix them now and commit the changes again. This ensures that it's easy for the Yii team to merge your changes with one click. -### 10. Having resolved any conflicts, push your code to github +### 8. Having resolved any conflicts, push your code to github ``` git push -u origin 999-name-of-your-branch-goes-here ``` The `-u` parameter ensures that your branch will now automatically push and pull from the github branch. That means -if you type `git push` the next time it will know where to push to. +if you type `git push` the next time it will know where to push to. This is useful if you want to later add more commits +to the pull request. -### 11. Open a [pull request](http://help.github.com/send-pull-requests/) against upstream. +### 9. Open a [pull request](http://help.github.com/send-pull-requests/) against upstream. Go to your repository on github and click "Pull Request", choose your branch on the right and enter some more details in the comment box. To link the pull request to the issue put anywhere in the pull comment `#999` where 999 is the issue number. -> Note that each pull-request should fix a single change. +> Note that each pull-request should fix a single change. For multiple, unrelated changes, please open multiple pull requests. -### 12. Someone will review your code +### 10. Someone will review your code Someone will review your code, and you might be asked to make some changes, if so go to step #6 (you don't need to open another pull request if your current one is still open). If your code is accepted it will be merged into the main branch and become part of the next Yii release. If not, don't be disheartened, different people need different features and Yii can't be everything to everyone, your code will still be available on github as a reference for people who need it. -### 13. Cleaning it up +### 11. Cleaning it up After your code was either accepted or declined you can delete branches you've worked with from your local repository and `origin`. diff --git a/docs/internals/report-an-issue.md b/docs/internals/report-an-issue.md index 99c9aa3..1705a11 100644 --- a/docs/internals/report-an-issue.md +++ b/docs/internals/report-an-issue.md @@ -6,6 +6,10 @@ Please follow the guidelines below when creating an issue so that your issue can * Provide information including: the version of PHP and Yii, the type of operating system and Web server, browser type and version; * Provide the **complete** error call stack if available. A screenshot to explain the issue is very welcome. * Describe the steps for reproducing the issue. It would be even better if you could provide code to reproduce the issue. +* If possible you may even create a failing unit test and [send it as a pull request](git-workflow.md). + +If the issue is related to one of the official extensions, please report it in the extension repositories issue tracker. +If you are unsure, [report it to the main repository](https://github.com/yiisoft/yii2/issues/new) (). **Do not report an issue if** diff --git a/docs/internals/translation-workflow.md b/docs/internals/translation-workflow.md index 2094e6c..3159a9c 100644 --- a/docs/internals/translation-workflow.md +++ b/docs/internals/translation-workflow.md @@ -7,8 +7,8 @@ where contribution is very welcome are documentation and framework messages. Framework messages ------------------ -Framework has two types of messages: exceptions that are intended to developer and are never translated and messages -that are actually visible to end user such as validation errors. +The framework has two types of messages: exceptions that are intended to developer and are never translated and messages +that are actually visible to the end user such as validation errors. In order to start with message translation: