Skip to content
Commits on Source (37)
Expand all Hide whitespace changes
Inline Side-by-side
README.txt 0 → 100644
View file @ a64e928e
DESCRIPTION
===========
The Drush Issue Queue Commands project (drush_iq) provides a set of
commands to interact with the issue queue on Drupal.org. These commands
make it easier for beginners and faster for beginning and experienced git
users alike to create and apply patches.
The commands provided by drush_iq includes:
iq-apply-patch Apply a patch from an issue.
iq-branch Manage branches created by iq commands.
iq-create-commit-comment Create a commit comment for an issue.
iq-diff Create a patch using `git format-patch`.
iq-info Show information about an issue.
iq-lint Run lint (php -l) on files that have changed.
iq-merge Merge patch back into the original branch.
iq-open Open a file changed by a patch.
iq-reset Return to the original branch.
iq-submit Post a patch to an issue.
For more information on these commands, see the "USAGE" section below.
For more information on creating and applying patches on drupal.org, see
the advanced patch contributor guide (http://drupal.org/node/1054616),
which descripts the process followed by the drush_iq commands.
REQUIREMENTS
============
drush_iq works with Drush version 7.x-5.x or Drush 8.x-6.x.
The iq-submit command also depends on the PHP cURL APIs.
INSTALLATION
============
$ drush dl drush_iq
$ drush dl drush_iq_extras
For instructions on installing the PHP cURL APIs, see:
http://www.php.net/manual/en/curl.installation.php
There are some user comments below the manual text that are
particularly helpful for some environments.
DRUSH IQ-SUBMIT CONFIGURATION
=============================
Drush iq-submit requires that your drupal.org username and password
be specified as options to the command. This identifies you to
drupal.org, and allows your uploaded patches to be correctly associated
with your account. Also, drupal.org does not allow anonymous
comments to be posted.
To avoid having to type your username and password every time you
use iq-submit, it is recommended that you configure a command-specific
option record in your drushrc.php file.
For example:
$command_specific['iq-submit']['user'] = 'troubador3';
$command_specific['iq-submit']['pass'] = 'correcthorsebatterystaple';
Note that drushrc.php files are executable PHP files; you can put any
executable PHP code you want inside them. For example, if you want
to store your drupal.org password in a separate file, you could do
somehting like this:
$home = drush_server_home();
$pw_file = $home . '/.drupalorgpw';
$command_specific['iq-submit']['pass'] = file_get_contents($pw_file);
USAGE - WORKFLOW FOR PATCH CONTRIBUTOR
======================================
If you have found a patch in the issue queue that you would like to work
on, the following workflow will allow you to contribute an updated patch
on the same issue.
0. Select a local Drupal project to work on
$ cd /path/to/drupal/sites/all/PROJECT
1. Download the project with Drush using git
$ drush pm-download PROJECT --package-handler=git_drupalorg --select
Select the desired development version from the list presented. The
version downloaded should match the version specified in the drupal.org issue.
2. Apply the latest patch from the issue
$ drush iq-apply-patch 12345-#6
Specify the issue number and the comment number contianing the patch you
would like to apply. If you specify an issue number without a comment number,
then drush iq-apply-patch will select the most recent patch. If no patch
number is given, iq-apply-patch will present a list of available patches
taken from a list of open windows containing issues on drupal.org. [*]
When iq-apply-patch applies the patch, it will create a new working
branch for the patch, and will commit the modified files. It will also
run the iq-lint command, which will warn you if the patch introduces any
syntax errors into any of the modified php files.
[*] Presently, drush iq-apply-patch can only read the open window list
on Linux. See: http://drupal.org/node/1864142
3. Open up a file changed by the patch
$ drush iq-open
If you have already set up an IDE to work on your site, you may prefer to
use features of your IDE to find the code you would like to work on. If
you are just making a quick change to a patched file, though, you might find
the iq-open command to be convenient. Drush iq-open will present a list of
all modified files, and will open the selected one using the configured
editor, as determined by the EDITOR environment variable.
If you would like to filter the list of presented files, you may use the
--search option to find files where the specified text was either added
or removed by the applied patch.
$ drush iq-open --search='some text added or removed by patch'
If you want to use Drush IQ to post an interdiff of your modified changes,
do not commit your changes to the working branch; leave them unstaged.
4. Test!
Unfortunately, there is no Drush iq-test command -- you still have to do
this step manually!
5. Inspect your changes
$ git diff
- or -
$ drush iq-diff
Run `git diff` to see your unstaged changes. If you do not commit
changes to the working branch, then you unstaged changes will correspond
to the interdiff between your latest work, and the patch at the time
it was originally applied.
Run `drush iq-diff` to show the complete, up-to-date changes to the module,
including the changes made in the original patch and your local modifications
combined together. Drush IQ uses `git format-patch` to create this diff,
so it will contain author information.
6. Submit your patch back to drupal.org
$ drush iq-submit 'This is my modest addition to your awesome patch'
The iq-submit command will use `git diff` to create an interdiff, and
`drush iq-diff` to create a complete patch. Both will be posted to the
original issue on drupal.org if the interdiff is small compared to the
size of the patch (30% of the size or less); otherwise, only the new,
complete patch will be posted.
USAGE - WORKFLOW FOR CREATING A NEW PATCH
=========================================
0. Select a local Drupal project to work on
$ cd /path/to/drupal/sites/all/PROJECT
1. Download the project with Drush using git
$ drush pm-download PROJECT --package-handler=git_drupalorg --select
Select the desired development version from the list presented. The
version downloaded should match the version specified in the drupal.org issue.
2. Make your modifications and test
3. Create a new issue on drupal.org
http://drupal.org/node/add/project-issue/PROJECT
Save the new issue, and make note of its issue number for use in the next
step.
4. Submit your patch on your issue
$ drush iq-submit 'Here is a novel approach to the problem described.' 12345
The second parameter to iq-submit should be the issue number of the
issue created in step 3, above.
USAGE - WORKFLOW FOR MODULE MANTAINERS
======================================
If someone has submitted a patch in the drupal.org issue queue for a module
that you maintain, the following workflow will allow you to easily apply,
test and commit the patch back to your modules' repository.
0. Select a local Drupal project to work on
$ cd /path/to/drupal/sites/all
1. Download the project following the git instructions on your project page
$ git clone --branch 7.x-1.x USERNAME@git.drupal.org:project/PROJECT.git
$ cd PROJECT
You probably already have a git checkout of your latest development
branch. If you don't, follow the git instructions found in the
Version Control tab of your project's project page:
http://drupal.org/project/PROJECT/git-instructions
If you already have cloned the project, make sure it is up to date via:
$ git pull
2. Apply the latest patch from the issue
$ drush iq-apply-patch 12345-#6
Apply the patch as described in the workflow for a patch contributor.
Note that iq-apply-patch will automatically use the --author option
when committing the patch to the working branch, so author credit will
be given, even if the contributor used `git diff` to create the patch.
3. Modify the submitted patch, if necessary, and test
Modification is optional, but be sure to test all submitted patches carefully.
4. Commit your changes as usual, using git:
$ git add .
$ git commit -m "Minor adjustment to contributor's excellent submission"
- or -
$ git add .
$ git commit --amend
Commit back to the working branch. Make multiple commits, if desired.
Use --amend if you'd like to merge trivial changes into the contributor's
commit without creating an additional commit of your own. This should
only be done for truly minor changes, like spelling corrections, etc.
5. Merge and push
$ drush iq-merge
$ git push
The iq-merge command can, if desired, squash all of the commits on the
working branch down into a single commit. Just specify the --squash
option to do this. If you always want to squash merged commits, set
up a command-specific option for iq-merge in your drushrc.php file:
$command_specific['iq-merge']['squash'] = TRUE;
Note that if you, the module maintainer, made a commit on the working
branch and then use --squash to compress multiple commits down to one,
you will ERASE the author credit for the other contributors with commits
on the working branch. To avoid erasing author credit, either use
--amend when committing, as recommended above, or avoid using --squash
when merging.
USAGE - WORKFLOW FOR CONTINUING DEVELOPMENT
===========================================
Not every issue can be resolved with a single patch; often, several
patches must be submitted before everything is done. Drush IQ provides
several ways to manage multiple and iterative issue development.
Resuming work on the main branch:
$ drush iq-reset
The drush iq-reset command will return you to the original branch.
IMPORTANT NOTE: If you have unstaged changes, they will remain
when you switch back to the original branch. If you want to keep
them separate, commit them first.
If you would like to delete all of your changes and your working
branch, you may add the --hard option to get rid of it. If the
modifications already exist in a patch on a drupal.org (e.g. if
submitted via iq-submit), then you can always re-apply them later
with iq-apply-patch.
If you commit rather than delete your changes, you can easily
switch back to them later:
$ drush iq-branch
The iq-branch command will list all of the branches that were
created by Drush IQ. You can easily switch back to resume work
on an issue by selecting the one you want from the list presented.
If you commit your changes after running iq-submit, and keep your
work-in-progress unstaged, then you may use iq-submit repeatedly
to submit new patches with interdiffs as work on your issue progresses.
GETTING INVOLVED / FUTURE ENHANCEMENTS
======================================
The workflows described above could be improved with the addition of
the following proposed features being tracked in the drush_iq issue queue:
http://drupal.org/node/1734884 - Add an iq-interdiff command
If Drush IQ had a command that could create interdiffs based on older
patches posted to the issue queue, then iq-submit could still create
an interdiff for a new patch, even if the newest changes had been
committed to the working branch.
http://drupal.org/node/1734888 - Make it easier to follow allong...
Drush IQ could do a better job at (a) applying a new patch from the issue
queue on top of an issue branch already created by drush iq-apply-patch,
and (b) updating your issue branch (committing changes, renaming the
branch) after an iq-submit.
For more Drush IQ issues, see the issue queue:
http://drupal.org/project/issues/drush_iq
docs/iq-commands.html deleted 100644 → 0
View file @ 6e825767
<h1>Drush Issue Queue Commands</h1>
<p>
Drush provides a set of commands to make interacting with the issue queue
on Drupal.org easier. In particular, the workflow described by the
<a href="http://drupal.org/node/1054616">advanced patch contributor guide</a> (<a href="http://drupal.org/node/1054616">http://drupal.org/node/1054616</a>)
is followed, so the patch files generated will contain information crediting
the authors. The Drush issue queue commands makes it much easier for beginners,
and much faster for beginning and experienced git users alike to create and
apply patches.
<h3>Applying Patches</h3>
<p>
Patches can be applied with the Drush iq-apply-patch command. The Drush iq
commands work best with projects that are cloned from their git repository
on Drupal.org, either by following the instructions at
http://drupal.org/project/project-name/git-instructions, or by using the
--package-handler=git_drupalorg modifier with Drush pm-download.
<pre>
$ drush pm-download uuid --package-handler=git_drupalorg
$ cd uuid
$ drush iq-apply-patch 1236768
</pre>
These commands may either be executed from within a working Drupal site,
or stand-alone, just to see what the patch looks like in context. If you
download the module into a working Drupal site, it is not necessary to
cd to the project directory before running the ip-apply-patch command; Drush
can find the project directory on its own.
<p>
Once you execute these commands, Drush will go out and find the most recent
patch that has been posted on the given project, and apply it using either
<i>git am</i> or <i>patch</i>, as appropriate. If you do not want to
apply the most recent patch, then you can append the comment number to the
end of the issue id; for example, to take the patch from the seventh comment
of issue 1236768:
<pre>
$drush iq-apply-patch 1236768-#7
</pre>
Finally, you might sometimes find it convenient to specify a patch via
the full URL to the issue node, like so:
<pre>
$drush iq-apply-patch http://drupal.org/node/1236768
</pre>
This form is handy to use when viewing a project's issue queue; you may
copy the issue URL to your clipboard by right-clicking on it, and then
paste it into a terminal window to use with iq-apply-patch, all without
needing to re-visit the issue in the browser to find the most recent patch.
<p>
Before the patch is applied, Drush will create a new branch to store your
changes in. This step is optional, and can be subverted by supplying the
<i>--no-git</i> option to iq-apply-patch. By default, most iq commands do not modify
the state of your repository; the automatic creation of the Drush iq branch
is one exception.
<h3>Creating Patches</h3>
<p>
After testing and modifying your patch, you may wish to create a new version
of the patch to post back to the issue queue. This may be done with the
Drush iq-diff command.
<pre>
$ drush iq-diff
</pre>
The iq-diff command will attempt to use the <i>git format-patch</i> to
create the patch, but if you do not desire this, the <i>--no-git</i> option
may be used to create a simple patch instead. Note that by design, the
<i>git format-patch</i> requires that all modified code be committed
to the issue branch before it can be included in the patch. The iq-diff command
will create a temporary commit to run the format-patch on, but it then
immediately backs the commit out again, leaving all of your changes in an
unstaged state. This is done so that the Drush iq commands can be used
quickly, without worrying about accumulating unwanted commits in your iq branch.
If you are a more experienced git user, and prefer to keep these commits around
to show the history of the patch's development, you may retain them by
specifying the <i>--commit</i> flag when running <i>drush iq-diff</i>.
<h3>Committing Changes</h3>
<p>
As previously mentioned, it is possible to commit changes to your iq branch
using the --commit flag with drush iq-diff. If you would prefer to commit
your changes via git directly, you may; in this instance, you might want to
use the iq-create-commit-comment command to facilitate a quick commit. The
iq-create-commit-comment command is aliased to ccc, so you can quickly commit
via:
<pre>
$ git add .
$ git commit -m "`drush ccc`"
</pre>
<h3>Cleaning Up</h3>
<p>
When you are done with an iq branch, you may clean it up with an iq-reset
command.
<pre>
$ drush iq-reset
</pre>
This will preserve your iq branch so that you may return to it later. Note
that in order for this to work correctly, you must commit your unstaged changes
to your iq branch first. If you do not commit, then all of your unstaged
changes will come with you when you return to the previous main branch that
the iq branch was split off from. This is standard git behavior, and the
iq commands maintain it.
<p>
If you are completely done with the iq branch, you may use the <i>--hard</i> option
to perminently delete it. Since it is easy to re-create the branch with
iq-apply-patch, it is safe to remove your iq branches after you have posted
your changes as a new patch on the issue.
iq.drush.inc
View file @ a64e928e
This diff is collapsed.
iqTest.php
View file @ a64e928e
......@@ -42,7 +42,7 @@ class iqTestCase extends Drush_CommandTestCase {
$this->assertFileExists(UNISH_SANDBOX . '/devel/README.txt');
chdir(UNISH_SANDBOX . '/devel');
$this->drush('iq-apply-patch', array('1262694'), $iq_apply_patch_options + $iq_include);
$this->drush('iq-apply-patch', array('1262694'), $iq_apply_patch_options + $iq_include + array('base' => 'devel-test'));
$this->drush('iq-diff', array(), $iq_include);
$output = $this->getOutput();
$this->assertContains("white-space: pre;", $output, 'Line added by patch');
......
runtests.sh
View file @ a64e928e
......@@ -11,8 +11,19 @@
DRUSH_PATH="`which drush`"
DRUSH_DIRNAME="`dirname -- "$DRUSH_PATH"`"
RUNNER="$DRUSH_DIRNAME/vendor/phpunit/phpunit/phpunit.php"
if [ ! -f "$RUNNER" ] ; then
RUNNER="`which phpunit`"
if [ ! -f "$RUNNER" ] ; then
echo "No phpunit found."
echo "- To install, run 'composer install --dev' from Drush directory."
exit 1
fi
fi
echo "Using phpunit at $RUNNER"
if [ $# = 0 ] ; then
phpunit --bootstrap="$DRUSH_DIRNAME/tests/drush_testcase.inc" .
$RUNNER --bootstrap="$DRUSH_DIRNAME/tests/drush_testcase.inc" .
else
phpunit --bootstrap="$DRUSH_DIRNAME/tests/drush_testcase.inc" "$@"
$RUNNER --bootstrap="$DRUSH_DIRNAME/tests/drush_testcase.inc" "$@"
fi