=for bif-doc #devintro

=head1 NAME

bif-doc-dev - how to hack on bif source files

=head1 DESCRIPTION


README.dev - how to hack on bif ---------------------------------

Congratulations on checking out the bif repository, and thanks for
taking the time and effort to contribute something back to the
community.

Dependencies ------------

We recommend the use of direnv (http://direnv.net) to keep bif
development dependencies away from the rest of your system. Once you
have that installed you can allow the local .envrc file from your copy
of the Git repository:

    direnv allow .

To build directly from the Git repository you need to install
dependencies using a cpanm that has the --with-develop option. The
cpanminus packages in the current stable versions of Ubuntu and Debian
do not. The latest cpanm version can be installed manually using curl
and perl as shown below.

    curl -L http://cpanmin.us | perl - --sudo App::cpanminus

Development dependencies can then be installed like so:

    cpanm --installdeps --with-develop $PWD

Tidy Code ---------

All Perl and POD content is expected to be "tidy" according to the
.perltidyrc and .podtidy-opts files in the source tree. The easiest way
to ensure this happens on commit is to run githook-perltidy
(automatically installed as one of the --with-develop dependencies):

    githook-perltidy install

Development bif script ----------------------

A test bif script is created in the tbin/ directory when you run
Makefile.PL.

    perl Makefile.PL
    export PATH=$PWD/tbin:$PATH    # if you don't use direnv
    which bif                      # tbin/bif

The great thing about direnv is that the local tbin/bif will be used
when your current directory is in the repository, but not when you are
elsewhere.

Personal Git Branches ---------------------

We encourage personal development branches in the git repository. Send
a request to the mailing list with your *public* ssh key (something
like $HOME/.ssh/id_rsa.pub) and your desired USERNAME (branch name).
Once the permissions are configured on the server then you can do
something like the following:

    # Tell git to use ssh authentication
    git config remote.origin.url ssh://git@bifax.org:bif.git

    # Create your own feature branch
    git checkout -b u/USERNAME/feature dev

    # $EDIT files
    git commit

    # Rebase your tree against most recent dev
    git fetch
    git rebase origin/dev

    # Upload and tell the mailing list what you have done
    git push --force origin u/USERNAME/feature

This allows anyone who clones the repository to see, modify and merge
your work from the command line, without having to visit a website to
find where all the forks are.


=head1 TOOLS

Check out the L<bif-list-tables> command to get a feel for the kinds of
data stored in the database, and which actions trigger events.

