Skip to content

Latest commit

 

History

History
163 lines (94 loc) · 3.24 KB

CONTRIBUTING.pod

File metadata and controls

163 lines (94 loc) · 3.24 KB

NAME

How to contribute to github-keygen?

DESCRIPTION

Patches are welcome!

They must be built against the master branch, then submitted as pull requests at GitHub.

The documentation is written using the POD format. Use the perldoc tool to render it in a terminal:

perldoc CONTRIBUTING.pod

INITIAL SETUP

1. Setup a Perl development environment

There are various ways to setup a Perl development environment, but here is mine (@dolmen). The key principles are:

a. Do not depend on the Perl of the operating system. Instead, install a recent version which you control upgrades independently of the O/S.
b. Setup environment to install Perl modules from CPAN into that perl using cpanm.

Step by step on MacOS (zsh):

a. Install plenv (note: this is incompatible with perlbrew)
git clone git://github.com/tokuhirom/plenv.git ~/.plenv
echo 'export PATH="$HOME/.plenv/bin:$PATH"' >> ~/.profile
echo 'eval "$(plenv init -)"' >> ~/.zshrc
exec $SHELL -l
git clone git://github.com/tokuhirom/Perl-Build.git ~/.plenv/plugins/perl-build/
b. Install a recent perl:
plenv install 5.40.1
plenv global 5.40.1
c. Install cpanm:
plenv install-cpanm

2. Get the source

git clone --origin upstream git://github.com/dolmen/github-keygen.git
cd github-keygen
git checkout master

3. Install build dependencies

Not required for doc patches.

curl -L https://cpanmin.us | perl - --installdeps --with-develop .

4. Setup a fork

4.1. Fork the project on GitHub
4.2. Link your local repo to your fork:

(You are already using github-keygen, aren't you?)

git remote add github <github-user>.github.com:<github-user>/github-keygen.git
git remote update

PATCHING, STEP BY STEP

1. Update your local fork
git remote update
git checkout master
git rebase upstream/master
2. Update Perl dependencies (not required for doc patches)
curl -L https://cpanmin.us | perl - --installdeps --with-develop .
3. Make your fix/feature in a dedicated Git branch
git checkout -b <my-patch> upstream/master

$EDITOR bin/github-keygen

# Test...
bin/github-keygen ...

# Run the author testsuite
prove -v xt

git commit
4. Submit your work
4.1 Push!
git push github <my-patch>
4.2 Submit a pull request on GitHub
5. Loop

Ready for another contribution? Redo from step 1!

FOR RELEASE MANAGER

  • Bump $VERSION

    git checkout master
# Bump version number
$EDITOR bin/github-keygen
# Update changelog
$EDITOR README.pod
git add bin/github-keygen README.pod
git commit

  • Release

    git checkout master
./release.pl -n
./release.pl
git push github master release
git push github --tags