Sindbad~EG File Manager

.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "App::WordPressTools::Contributing 3"
.TH App::WordPressTools::Contributing 3 "2018-09-14" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
App::WordPressTools::Contributing \- How to contribute to wp\-tools
.SH "GETTING INVOLVED"
.IX Header "GETTING INVOLVED"
If you'd like to contribute a patch to improve the wp-tools documentation or tests, fix a bug, or add a new feature,
we think that's great. Here's how to do it:
.SS "Get the Code"
.IX Subsection "Get the Code"
.IP "1." 4
Clone the repository.
.Sp
If you use GitHub, fork wp-tools and then clone your fork:
.Sp
.Vb 1
\&    git clone git@github.com:$GITHUB_USERNAME/wp\-tools.git
.Ve
.Sp
If you don't use GitHub, you can clone the official repository:
.Sp
.Vb 1
\&    git clone https://github.com/bluehost/wp\-tools.git
.Ve
.IP "2." 4
Install Dist::Zilla.
.Sp
.Vb 1
\&    cpanm Dist::Zilla
.Ve
.IP "3." 4
Install the Perl dependencies using Dist::Zilla:
.Sp
.Vb 2
\&    dzil authordeps \-\-missing | cpanm
\&    dzil listdeps \-\-author \-\-develop \-\-missing | cpanm
.Ve
.IP "4." 4
Make sure the tests pass:
.Sp
.Vb 1
\&    dzil test
.Ve
.SS "Repository Structure"
.IX Subsection "Repository Structure"
.IP "lib" 4
.IX Item "lib"
Contains source code and source documentation in the form of Perl modules and \s-1POD\s0 files.
.IP "script" 4
.IX Item "script"
Contains executable source code.
.IP "t" 4
.IX Item "t"
Contains test scripts.
.IP "maint" 4
.IX Item "maint"
Contains release management scripts.
.IP "\s-1CONTRIBUTING\s0.md, \s-1LICENSE, README\s0.md" 4
.IX Item "CONTRIBUTING.md, LICENSE, README.md"
Rendered documentation. Do \fB\s-1NOT\s0\fR modify these files directly because their contents are built from other files. You may
commit changes to these files as long as their source files were updated.
.IP "Changes" 4
.IX Item "Changes"
Lists releases and associated changes.
.SS "Branch Layout"
.IX Subsection "Branch Layout"
.IP "master" 4
.IX Item "master"
This is the shared development branch. It may contain accepted but unreleased commits, but it does not include anything
that is known to be broken or a \s-1WIP\s0 \*(-- that's what topics are for. Topics should be branched from master.
.IP "release" 4
.IX Item "release"
The release branch tracks master but lags behind. The tip of this branch always points to the latest release commit, so
this branch is the \fBstable\fR branch.
.IP "topic/*" 4
.IX Item "topic/*"
Topics are branched from master and may contain experimental and broken code. They are for work in progress. Topics may
be rebased and cleaned up for eventual merging back into master. Topics may be namespaced \*(L"topic/\*(R" or not.
.IP "dist" 4
.IX Item "dist"
The dist branch includes releases built for distribution to the \s-1CPAN.\s0 This branch shares no commits with any other
branch and is maintained by release management scripts.
.IP "solo" 4
.IX Item "solo"
The solo branch includes releases built as standalone scripts (for curl installation). This branch shares no commits
with any other branch and is maintained by release management scripts.
.SS "Commit Guidelines"
.IX Subsection "Commit Guidelines"
In general, follow the Commit Guidelines <https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines>
from the Pro Git <https://git-scm.com/book/en/v2> book. In particular:
.IP "\(bu" 4
Clean up your branch.
.Sp
Remember that your topic branch is yours. You can and should rewrite its history so that its history is clean and
straightforward without any \*(L"fixup\*(R" commits. These commands can help you clean up your history:
.Sp
.Vb 3
\&    git commit \-\-amend
\&    git rebase \-\-interactive
\&    git cherry\-pick
.Ve
.IP "\(bu" 4
Follow the same code style already used in the file(s) you're editing.
.IP "\(bu" 4
Fix whitespace errors.
.Sp
Use \f(CW\*(C`git diff \-\-check\*(C'\fR to get a list of potential whitespace errors.
.IP "\(bu" 4
Rebase on the latest master.
.Sp
In order to make sure your topic will merge back with master without conflicts, rebase your topic onto the tip of
master. If there are conflicts, resolve them.
.Sp
.Vb 2
\&    git checkout $TOPIC_BRANCH
\&    git pull \-\-rebase origin master
.Ve
.IP "\(bu" 4
Add documentation for new features.
.IP "\(bu" 4
Add tests.
.IP "\(bu" 4
Write good commit messages.
.Sp
The commit message \*(L"subject\*(R" is on the first line and should be 50 characters or less. If the commit needs more
explanation, the commit message \*(L"body\*(R" then comes after an empty line and is wrapped to about 72 characters.
.SS "Development Workflow"
.IX Subsection "Development Workflow"
Before you start, you may want to read and make sure you understand the \*(L"Commit Guidelines\*(R", \*(L"Directory Structure\*(R",
and \*(L"Branch Layout\*(R".
.IP "1." 4
Branch your topic from master:
.Sp
.Vb 1
\&    git checkout \-b $TOPIC_BRANCH master
.Ve
.IP "2." 4
Make your changes in a logical sequence of one or more commits.
.Sp
See \*(L"Commit Guidelines\*(R".
.IP "3." 4
Make sure the tests still pass:
.Sp
.Vb 1
\&    dzil test
.Ve
.IP "4." 4
Send your patches to the authors.
.Sp
If you use GitHub, you can push your topic branch to your fork and then create a pull request back to our master branch
using the GitHub interface:
.Sp
.Vb 1
\&    git push origin $TOPIC_BRANCH
.Ve
.Sp
If you don't use GitHub, send your patch to the authors via email:
.Sp
.Vb 2
\&    git checkout $TOPIC_BRANCH
\&    git format\-patch \-M origin
\&
\&    # Then send patches as attachments using your favorite email client or using git:
\&    git send\-email *.patch
.Ve
.Sp
See Public Project over Email <https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#Public-Project-over-Email>
from the Pro Git <https://git-scm.com/book/en/v2> book for instructions on configuring git for sending email.
.SS "Release Workflow"
.IX Subsection "Release Workflow"
We use Dist::Zilla to manage releases. The release management scripts do pretty much all of the work.
.IP "1." 4
Write to the changelog.
.Sp
First, take a look at the list of commits since the last release:
.Sp
.Vb 1
\&    git shortlog origin/release..master
.Ve
.Sp
Then edit \fIChanges\fR and summarize the changes after the \f(CW\*(C`{{$NEXT}}\*(C'\fR token. Just leave the file uncommitted; it will
automatically be committed in the next step.
.IP "2." 4
Run the release script and follow the prompts:
.Sp
.Vb 2
\&    git checkout master
\&    dzil release
.Ve
.Sp
The release script will take care of making the release commit (with \fIChanges\fR), tagging, and uploading to the \s-1CPAN.\s0