Permalink
Browse files

Converting plaintext documentation to markdown. Cleaning up markup, r…

…eferencing nicknames directly for usage within Github
  • Loading branch information...
1 parent 95ba0d7 commit 3f424cfa78cb7e8e4eab6e3ca346c9feb8017564 @Ocramius Ocramius committed Mar 8, 2012
Showing with 429 additions and 421 deletions.
  1. +63 −0 README-DEV.md
  2. +0 −64 README-DEV.txt
  3. +221 −0 README-GIT.md
  4. +0 −211 README-GIT.txt
  5. +145 −0 README.md
  6. +0 −146 README.txt
View
@@ -0,0 +1,63 @@
+# CONTRIBUTING
+
+## RESOURCES
+
+If you wish to contribute to Zend Framework, please be sure to
+read/subscribe to the following resources:
+
+ - ZF2 Requirements:
+ http://framework.zend.com/wiki/display/ZFDEV2/Zend+Framework+2.0+Requirements
+ - Coding Standards:
+ http://framework.zend.com/manual/en/coding-standard.html
+ - ZF Git Guide:
+ README-GIT.txt
+ - Contributor's Guide:
+ http://framework.zend.com/wiki/display/ZFDEV/Contributing+to+Zend+Framework
+ - ZF Contributor's mailing list:
+ Archives: http://zend-framework-community.634137.n4.nabble.com/ZF-Contributor-f680267.html
+ Subscribe: zf-contributors-subscribe@lists.zend.com
+ - ZF Contributor's IRC channel:
+ #zftalk.dev on Freenode.net
+
+If you are working on new features, or refactoring an existing
+component, please create a proposal. You can do this in on the proposals
+page, http://framework.zend.com/wiki/display/ZFPROP/Home.
+
+## RUNNING TESTS
+
+The full test suite currently does not run! This is due to some
+components not yet being migrated to namespaces, as well as to some
+issues we've encountered in refactoring.
+
+To run tests:
+
+ - Make sure you have a recent version of PHPUnit installed; 3.5.0
+ minimally.
+ - Enter the `tests/` subdirectory.
+ - Execute PHPUnit, providing a path to a component directory for which
+ you wish to run tests, or a specific test class file.
+
+ ```bash
+ % phpunit ZendTest/Application
+ % phpunit ZendTest/Application/Resource/CacheManagerTest.php
+ ```
+
+ - You may also provide the `--group` switch; in such cases, provide the
+ top-level component name:
+
+ ```bash
+ % phpunit --group Zend_Application
+ ```
+ This will likely lead to errors, so it's usually best to specify a
+ specific component in which to run test:
+
+ ```bash
+ % phpunit --group ZF-XYZ Zend/Application
+ ```
+You can turn on conditional tests with the TestConfiguration.php file.
+To do so:
+
+ - Enter the `tests/` subdirectory.
+ - Copy `TestConfiguration.php.dist` file to `TestConfiguration.php`
+ - Edit `TestConfiguration.php` to enable any specific functionality you
+ want to test, as well as to provide test values to utilize.
View
@@ -1,64 +0,0 @@
-If you wish to contribute to Zend Framework, please be sure to
-read/subscribe to the following resources:
-
- * ZF2 Requirements:
- http://framework.zend.com/wiki/display/ZFDEV2/Zend+Framework+2.0+Requirements
-
- * Coding Standards:
- http://framework.zend.com/manual/en/coding-standard.html
-
- * ZF Git Guide:
- README-GIT.txt
-
- * Contributor's Guide:
- http://framework.zend.com/wiki/display/ZFDEV/Contributing+to+Zend+Framework
-
- * ZF Contributor's mailing list:
- Archives: http://zend-framework-community.634137.n4.nabble.com/ZF-Contributor-f680267.html
- Subscribe: zf-contributors-subscribe@lists.zend.com
-
- * ZF Contributor's IRC channel:
- #zftalk.dev on Freenode.net
-
-If you are working on new features, or refactoring an existing
-component, please create a proposal. You can do this in on the proposals
-page, http://framework.zend.com/wiki/display/ZFPROP/Home.
-
-RUNNING TESTS
-=============
-The full test suite currently does not run! This is due to some
-components not yet being migrated to namespaces, as well as to some
-issues we've encountered in refactoring.
-
-To run tests:
-
- * Make sure you have a recent version of PHPUnit installed; 3.5.0
- minimally.
-
- * Enter the tests/ subdirectory.
-
- * Execute PHPUnit, providing a path to a component directory for which
- you wish to run tests, or a specific test class file.
-
- % phpunit ZendTest/Application
- % phpunit ZendTest/Application/Resource/CacheManagerTest.php
-
- * You may also provide the "--group" switch; in such cases, provide the
- top-level component name:
-
- % phpunit --group Zend_Application
-
- This will likely lead to errors, so it's usually best to specify a
- specific component in which to run test:
-
- % phpunit --group ZF-XYZ Zend/Application
-
-You can turn on conditional tests with the TestConfiguration.php file.
-To do so:
-
- * Enter the tests/ subdirectory.
-
- * Copy TestConfiguration.php.dist file to TestConfiguration.php
-
- * Edit TestConfiguration.php to enable any specific functionality you
- want to test, as well as to provide test values to utilize.
View
@@ -0,0 +1,221 @@
+# USING THE GIT REPOSITORY
+
+## Initial Setup
+
+First, make sure you know the email address associated with your JIRA
+credentials. All commits pushed to the master repository are checked
+against these addresses, so your repository will need to be configured
+to use that address. The following will give you that information:
+
+ 1. Visit the ZF Crowd install: http://framework.zend.com/crowd
+ 2. Log in, if you aren't.
+ 3. Find the "My Profile" link in the upper right of the page, and follow
+ it.
+ 4. The resulting page will display your profile, including the _email_
+ address with which you are registered. Make a note of it.
+
+## Setup your own public repository
+
+Your next step is to establish a public repository from which we can
+pull your work into the master repository. You have two options: use
+github or other public site, or setup/use your own repository.
+
+### Option 1: GitHub
+
+ 1. Setup a GitHub account (http://github.com/), if you haven't yet
+ 2. Fork the ZF2 respository (http://github.com/zendframework/zf2)
+ 3. Clone your fork locally and enter it (use your own GitHub username
+ in the statement below)
+
+ ```bash
+ % git clone git@github.com:<username>/zf2.git
+ % cd zf2
+ ```
+
+ 4. Configure git to use the email address with which you are registered
+ in JIRA:
+
+ ```bash
+ % git config user.email <your email address>
+ ```
+
+ 5. Add a remote to the canonical ZF repository, so you can keep your fork
+ up-to-date:
+
+ ```bash
+ % git remote add zf2 https://github.com/zendframework/zf2.git
+ % git fetch zf2
+ ```
+
+### Option 2: Personal Repository
+
+We assume you will use gitosis (http://progit.org/book/ch4-7.html) or gitolite
+(http://progit.org/book/ch4-8.html) to host your own repository. If
+you go this route, we will assume you have the knowledge to do so, or
+know where to obtain it. We will not assist you in setting up such a
+repository.
+
+ 1. Create a new repository
+
+ ```bash
+ % git init
+ ```
+
+ 2. Configure git to use the email address with which you are registered
+ in JIRA:
+
+ ```bash
+ % git config user.email <your email address>
+ ```
+
+ 3. Add an "origin" remote pointing to your gitosis/gitolite repo:
+
+ ```bash
+ % git remote add origin git://yourdomain/yourrepo.git
+ ```
+
+ 4. Add a remote for the ZF repository and fetch it
+
+ ```bash
+ % git remote add zf2 https://github.com/zendframework/zf2.git
+ % git fetch zf2
+ ```
+
+ 5. Create a new branch for the ZF repository (named "zf/master" here)
+
+ ```bash
+ % git branch -b zf/master zf2/master
+ ```
+
+ 6. Create your master branch off the ZF branch, and push to your
+ repository
+
+ ```bash
+ % git branch -b master
+ % git push origin HEAD:master
+ ```
+
+## Keeping Up-to-Date
+
+Periodically, you should update your fork or personal repository to
+match the canonical ZF repository. In each of the above setups, we have
+added a remote to the Zend Framework repository, which allows you to do
+the following:
+
+
+```bash
+% git checkout master
+% git pull zf2 master
+- OPTIONALLY, to keep your remote up-to-date -
+% git push origin
+```
+
+## Working on Zend Framework
+
+When working on Zend Framework, we recommend you do each new feature or
+bugfix in a new branch. This simplifies the task of code review as well
+as of merging your changes into the canonical repository.
+
+A typical work flow will then consist of the following:
+
+ 1. Create a new local branch based off your master branch.
+ 2. Switch to your new local branch. (This step can be combined with the
+ previous step with the use of `git checkout -b`.)
+ 3. Do some work, commit, repeat as necessary.
+ 4. Push the local branch to your remote repository.
+ 5. Send a pull request.
+
+The mechanics of this process are actually quite trivial. Below, we will
+create a branch for fixing an issue in the tracker.
+
+```bash
+% git checkout -b zf9295
+Switched to a new branch 'zf9295'
+```
+... do some work ...
+
+```bash
+% git commit
+```
+... write your log message ...
+
+```bash
+% git push origin HEAD:zf9295
+Counting objects: 38, done.
+Delta compression using up to 2 threads.
+Compression objects: 100% (18/18), done.
+Writing objects: 100% (20/20), 8.19KiB, done.
+Total 20 (delta 12), reused 0 (delta 0)
+To ssh://git@github.com/weierophinney/zf2.git
+ b5583aa..4f51698 HEAD -> master
+```
+
+
+To send a pull request, you have two options.
+
+If using GitHub, you can do the pull request from there. Navigate to
+your repository, select the branch you just created, and then select the
+"Pull Request" button in the upper right. Select the user
+"zendframework" as the recipient.
+
+If using your own repository - or even if using GitHub - you can send an
+email indicating you have changes to pull:
+
+ - Send to <zf-devteam@zend.com>
+
+ - In your message, specify:
+ - The URL to your repository (e.g., `git://mwop.net/zf2.git`)
+ - The branch containing the changes you want pulled (e.g., `zf9295`)
+ - The nature of the changes (e.g., `implements
+ Zend_Service_Twitter`, `fixes ZF-9295`, etc.)
+
+## Branch Cleanup
+
+As you might imagine, if you are a frequent contributor, you'll start to
+get a ton of branches both locally and on your remote.
+
+Once you know that your changes have been accepted to the master
+repository, we suggest doing some cleanup of these branches.
+
+ - Local branch cleanup
+
+ ```bash
+ % git branch -d <branchname>
+ ```
+
+ - Remote branch removal
+
+ ```bash
+ % git push origin :<branchname>
+ ```
+
+
+## FEEDS AND EMAILS
+
+RSS feeds may be found at:
+
+https://github.com/zendframework/zf2/commits/<branch>.atom
+
+where <branch> is a branch in the repository.
+
+To subscribe to git email notifications, send an email to:
+
+<zf-git-subscribe@lists.zend.com>
+
+You will need to reply to the verification email sent to you by this
+list.
+
+Should you wish to filter emails from the list, they will use the
+"subject" line of commit messages, preceded by `[branch] `, and come
+from <zf-git@lists.zend.com>.
+
+## CONTRIBUTORS AND COMMITTERS
+
+For the immediate future, and until we create a community process team,
+only the Zend team will be committers. If you have a patch or
+feature-set you wish to have incorporated into the repository, please
+issue a pull request to a committer. A pull request may be done by using
+git's "git-send-email" functionality, or by sending a request to a
+committer indicating the URL of your repository, the branch that should
+be pulled, and/or the specific revision(s) to pull.
+
Oops, something went wrong.

0 comments on commit 3f424cf

Please sign in to comment.