pidgin/pidgin
Clone
Summary
Browse
Changes
Graph
Ignore pidginprivate.h from the docs
2021-05-13, Gary Kramlich
1b5b70f24f62
Ignore pidginprivate.h from the docs
Testing Done:
Ran docs locally, had to remove the html and xml directories to have a clean build.
Reviewed at https://reviews.imfreedom.org/r/653/
<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<chapter
id=
"chapter-code-contributions"
>
<title>
Code
Contributions
</title>
<sect2
id=
"introduction"
>
<title>
Introduction
</title>
<para>
All
of
the
Pidgin
related
projects
use
<ulink
url=
"https://reviewboard.org"
>
Review
Board
</ulink>
for
handling
contributions
at
<ulink
url=
"https://reviews.imfreedom.org"
>
reviews.imfreedom.org
</ulink>
.
</para>
</sect2>
<sect2
id=
"first-time-setup"
>
<title>
First
Time
Setup
</title>
<para>
There
are
a
few
things
you'll
need
to
set
up
to
be
able
to
submit
a
code
review
to
these
projects.
This
includes
installing
<ulink
url=
"https://www.reviewboard.org/downloads/rbtools/"
>
RBTools
</ulink>
as
well
as
some
additional
<ulink
url=
"https://www.mercurial-scm.org/"
>
Mercurial
</ulink>
configuration.
</para>
<sect3
id=
"install-rbtools"
>
<title>
Install
RBTools
</title>
<para>
The
recommended
way
to
install
RBTools
is
via
pip
and
can
be
done
with
the
following
command.
</para>
<programlisting>
pip3
install
-U
"RBTools>=1.0.3"
</programlisting>
<para>
Once
RBTools
is
installed
you
need
to
make
sure
that
<code>
rbt
</code>
is
available
on
your
<code>
$PATH
</code>
.
To
do
this,
you
may
need
to
add
<code>
$HOME/.local/bin
</code>
to
your
<code>
$PATH
</code>
.
The
exact
procedure
to
do
this
is
dependent
on
your
setup
and
outside
of
the
scope
of
this
document.
</para>
</sect3>
<sect3
id=
"configure-mercurial"
>
<title>
Mercurial
Configuration
</title>
<para>
This
configuration
for
Mercurial
is
to
make
your
life
as
a
contributor
easier.
There
a
few
different
ways
to
configure
Mercurial,
but
these
instructions
will
update
your
user
specific
configuration
in
<code>
$HOME/.hgrc
</code>
.
</para>
<para>
The
first
thing
we
need
to
do
is
to
install
the
evolve
extension.
This
extension
makes
rewriting
history
safe
and
we
use
it
extensively
in
our
repositories.
You
can
install
it
with
a
simple
<code>
pip3
install
-U
hg-evolve
</code>
.
We
will
enable
it
below
with
some
other
bundled
extensions,
but
you
can
find
more
information
about
it
<ulink
url=
"https://www.mercurial-scm.org/wiki/EvolveExtension"
>
here
</ulink>
.
</para>
<para>
When
working
with
Mercurial
repositories
it
is
very
important
to
make
sure
that
your
username
is
set
properly
as
it
is
added
to
every
commit
you
make.
To
set
your
username
you
must
add
it
to
the
<code>
[ui]
</code>
section
in
your
<code>
$HOME/.hgrc
</code>
like
the
following
example.
</para>
<programlisting>
[ui]
username
=
Full
Name
<
email@example.com
>
</programlisting>
<para>
Next
we
need
to
make
sure
that
the
<emphasis>
evolve
</emphasis>
and
<emphasis>
rebase
</emphasis>
extensions
are
loaded.
To
do
so
add
the
lines
in
the
following
example.
You
do
not
need
to
put
anything
after
the
<code>
=
</code>
as
this
will
tell
Mercurial
to
look
for
them
in
the
default
places
for
extensions.
</para>
<programlisting>
[extensions]
evolve
=
rebase
=
</programlisting>
<para>
Next
we're
going
to
create
a
<emphasis>
revsetalias
</emphasis>
.
This
will
be
used
to
make
it
easier
to
look
at
your
history
and
submit
your
review
request.
</para>
<programlisting>
[revsetalias]
wip
=
only(.,default)
</programlisting>
<para>
This
alias
will
show
us
just
the
commits
that
are
on
our
working
branch
and
not
on
the
default
branch.
The
default
branch
is
where
all
accepted
code
contributions
go.
Optionally,
you
can
add
the
<code>
wip
</code>
command
alias
below
which
will
show
you
the
revision
history
of
what
you
are
working
on.
</para>
<programlisting>
[alias]
wip
=
log
--graph
--rev
wip
</programlisting>
<para>
There
are
quite
a
few
other
useful
configuration
changes
you
can
make,
and
a
few
examples
can
be
found
below.
</para>
<programlisting>
[ui]
#
update
a
large
number
of
settings
for
a
better
user
experience,
highly
#
recommended!!
tweakdefaults
=
true
[alias]
#
make
hg
log
show
the
graph
as
well
as
commit
phase
lg
=
log
--graph
--template
phases
</programlisting>
<para>
Below
is
all
of
the
above
configuration
settings
to
make
it
easier
to
copy/paste.
</para>
<programlisting>
[ui]
username
=
Full
Name
<
email@example.com
>
#
update
a
large
number
of
settings
for
a
better
user
experience,
highly
#
recommended!!
tweakdefaults
=
true
[extensions]
evolve
=
rebase
=
[alias]
#
make
hg
log
show
the
graph
as
well
as
commit
phase
lg
=
log
--graph
--template
phases
#
show
everything
between
the
upstream
and
your
wip
wip
=
log
--graph
--rev
wip
[revsetalias]
wip
=
only(.,default)
</programlisting>
</sect3>
<sect3
id=
"login"
>
<title>
Log
in
to
Review
Board
</title>
<para>
To
be
able
to
submit
a
review
request
you
need
to
have
an
account
on
our
JetBrains
Hub
instance
at
<ulink
url=
"https://hub.imfreedom.org"
>
hub.imfreedom.org
</ulink>
.
You
can
create
an
account
here
in
a
number
of
ways
and
even
turn
on
two
factor
authentication.
But
please
note
that
if
you
turn
on
two
factor
authentication
you
will
need
to
create
an
application
password
to
be
able
to
login
to
Review
Board.
</para>
<para>
Once
you
have
that
account
you
can
use
it
to
login
our
Review
Board
instance
at
<ulink
url=
"https://reviews.imfreedom.org"
>
reviews.imfreedom.org
</ulink>
.
Please
note,
you
will
have
to
login
via
the
web
interface
before
being
able
to
use
RBTools.
</para>
<para>
Once
you
have
an
account
and
have
logged
into
our
Review
Board
site,
you
can
begin
using
RBTools.
In
your
shell,
navigate
to
a
Mercurial
clone
of
one
of
the
Pidgin
or
purple-related
projects,
then
run
the
<code>
rbt
login
</code>
command.
You
should
only
need
to
do
this
once,
unless
you
change
your
password
or
have
run
the
<code>
rbt
logout
</code>
command.
</para>
</sect3>
</sect2>
<sect2
id=
"create"
>
<title>
Creating
a
New
Review
Request
</title>
<para>
Before
starting
a
new
review
request,
you
should
make
sure
that
your
local
copy
of
the
repository
is
up
to
date.
To
do
so,
make
sure
you
are
on
the
<emphasis>
default
</emphasis>
branch
via
<code>
hg
update
default
</code>
.
Once
you
are
on
the
<emphasis>
default
</emphasis>
branch,
you
can
update
your
copy
with
<code>
hg
pull
--update
</code>
.
Now
that
you're
starting
with
the
most
recent
code,
you
can
proceed
with
your
contributions.
</para>
<para>
While
it's
not
mandatory,
it
is
highly
recommended
that
you
work
on
your
contributions
via
a
branch.
If
you
don't
go
this
path,
you
will
have
issues
after
your
review
request
is
merged.
This
branch
name
can
be
whatever
you
like
as
it
will
not
end
up
in
the
main
repositories,
and
you
can
delete
it
from
your
local
repository
after
it
is
merged.
See
<link
linkend=
"cleanup"
>
cleanup
</link>
for
more
information.
</para>
<para>
You
can
create
the
branch
with
the
following
command:
</para>
<programlisting>
hg
branch
my-new-branch-name
</programlisting>
<para>
Now
that
you
have
a
branch
started,
you
can
go
ahead
and
work
like
you
normally
would,
committing
your
code
at
logical
times,
etc.
Once
you
have
some
work
committed
and
you
are
ready
to
create
a
new
review
request,
you
can
type
<code>
rbt
post
wip
</code>
and
you
should
be
good
to
go.
This
will
create
a
new
review
request
using
all
of
the
committed
work
in
your
repository
and
will
output
something
like
below.
</para>
<programlisting
language=
"screen"
>
Review
request
#403
posted.
https://reviews.imfreedom.org/r/403/
https://reviews.imfreedom.org/r/403/diff/
</programlisting>
<para>
At
this
point,
your
review
request
has
been
posted,
but
it
is
not
yet
published.
This
means
no
one
can
review
it
yet.
To
do
that,
you
need
to
go
to
the
URL
that
was
output
from
your
<code>
rbt
post
</code>
command
and
verify
that
everything
looks
correct.
If
this
review
request
fixes
any
bugs,
please
make
sure
to
enter
their
numbers
in
the
bugs
field
on
the
right.
Also,
be
sure
to
review
the
actual
diff
yourself
to
make
sure
it
includes
what
you
intended
it
to
and
nothing
extra.
</para>
<para>
Once
you
are
happy
with
the
review
request,
you
can
hit
the
publish
button
which
will
make
the
review
request
public
and
alert
the
reviewers
of
its
creation.
Optionally
you
can
pass
<code>
--open
</code>
to
<code>
rbt
post
</code>
in
the
future
to
automatically
open
the
draft
review
in
your
web
browser.
</para>
<para>
<code>
rbt
post
</code>
has
a
ton
of
options,
so
be
sure
to
check
them
out
with
<code>
rbt
post
--help
</code>
.
There
are
even
options
to
automatically
fill
out
the
bugs
fixed
fields
among
other
things.
</para>
</sect2>
<sect2
id=
"update"
>
<title>
Updating
an
Existing
Review
Request
</title>
<para>
Typically
with
a
code
review,
you're
going
to
need
to
make
some
updates.
However
there's
also
a
good
chance
that
your
original
branching
point
has
changed
as
other
contributions
are
accepted.
To
deal
with
this
you'll
need
to
rebase
your
branch
on
top
of
the
new
changes.
</para>
<para>
Rebasing,
as
the
name
suggests
is
the
act
of
replaying
your
previous
commits
on
top
of
a
new
base
revision.
Mercurial
makes
this
pretty
easy.
First,
make
sure
you
are
on
your
branch
with
<code>
hg
up
my-branch-name
</code>
.
Now
you
can
preview
the
rebase
with
<code>
hg
rebase
-d
default
--keepbranches
--dry-run
</code>
.
We
prefer
doing
a
dry-run
just
to
make
sure
there
aren't
any
major
surprises.
You
may
run
into
some
conflicts,
but
those
will
have
to
be
fixed
regardless.
</para>
<para>
If
everything
looks
good,
you
can
run
the
actual
rebase
with
<code>
hg
rebase
-d
default
--keepbranches
</code>
.
Again
if
you
run
into
any
conflicts,
you
will
have
to
resolve
them
and
they
will
cause
the
dry-run
to
fail.
Once
you
have
fixed
the
merge
conflicts,
you'll
then
need
to
mark
the
files
as
resolved
with
<code>
hg
resolve
--mark
filename
</code>
.
When
you
have
resolved
all
of
the
conflicted
files
you
can
continue
the
rebase
with
<code>
hg
rebase
--continue
</code>
.
You
may
run
into
multiple
conflicts,
so
just
repeat
until
you're
done.
</para>
<para>
After
rebasing
you
can
start
addressing
the
comments
in
your
review
and
commit
them.
Once
they
are
committed,
you
can
update
your
existing
review
request
with
<code>
rbt
post
--update
</code>
.
If
for
some
reason
<code>
rbt
</code>
can
not
figure
out
the
proper
review
request
to
update,
you
can
pass
the
number
in
via
<code>
rbt
post
--review-request-id
#
</code>
.
Note
that
when
using
<code>
--review-request-id
</code>
you
no
longer
need
to
specify
<code>
--update
</code>
.
</para>
<para>
Just
like
an
initial
<code>
rbt
post
</code>
,
the
updated
version
will
be
in
a
draft
state
until
you
publish
it.
So
again,
you'll
need
to
visit
the
URL
that
was
output,
verify
everything,
and
click
the
publish
button.
</para>
</sect2>
<sect2
id=
"land"
>
<title>
Landing
a
Review
Request
</title>
<para>
This
will
typically
only
be
done
by
the
Pidgin
developers
with
push
access.
If
you
want
to
test
a
patch
from
a
review
request,
please
see
the
<link
linkend=
"patch"
>
patch
</link>
section
below.
</para>
<para>
It
is
<emphasis>
HIGHLY
</emphasis>
recommended
that
you
use
a
separate
clone
of
the
repository
in
question
when
you
want
to
land
review
requests.
This
makes
it
much
easier
to
avoid
accidentally
pushing
development
work
to
the
canonical
repository
which
makes
everyone's
life
easier.
Also,
the
mainline
repositories
now
auto
publish,
so
if
you
do
not
selectively
push
commits,
all
of
your
draft
commits
will
be
published.
You
can
name
this
additional
clone
whatever
you
like,
but
using
something
like
<code>
pidgin-clean
</code>
is
a
fairly
common
practice.
This
makes
it
easy
for
you
to
know
that
this
clone
is
only
meant
for
landing
review
requests,
and
other
admistrative
work
like
updating
the
ChangeLog
and
COPYRIGHT
files.
</para>
<para>
When
you
are
ready
to
land
a
review
request
you
need
to
make
sure
you
are
on
the
proper
branch.
In
most
cases
this
will
be
the
branch
named
<emphasis>
default
</emphasis>
and
can
be
verified
by
running
the
command
<code>
hg
branch
</code>
.
Next
you
need
to
make
sure
that
your
local
copy
is
up
to
date.
You
can
do
this
by
running
<code>
hg
pull
--update
</code>
.
</para>
<para>
Please
note,
if
you
run
<code>
hg
pull
</code>
and
then
immediately
run
<code>
hg
pull
--update
</code>
you
will
<emphasis>
not
</emphasis>
update
to
the
most
recent
commit
as
this
new
invocation
of
<code>
hg
pull
</code>
has
not
actually
pulled
in
any
new
commits.
To
properly
update,
you'll
need
to
run
<code>
hg
update
</code>
instead.
</para>
<para>
Once
your
local
copy
is
up
to
date
you
can
land
the
review
request
with
<code>
rbt
land
--no-push
--review-request-id
#
</code>
where
<code>
#
</code>
is
the
number
of
the
review
request
you
are
landing.
The
<code>
--no-push
</code>
argument
is
to
disable
pushing
this
commit
immediately.
Most
of
our
configuration
already
enables
this
flag
for
you,
but
if
you're
in
doubt,
please
use
the
<code>
--no-push
</code>
argument.
</para>
<para>
Once
the
review
request
has
been
landed,
make
sure
to
verify
that
the
revision
history
looks
correct,
run
a
test
build
as
well
as
the
unit
tests,
and
if
everything
looks
good,
you
can
continue
with
the
housekeeping
before
we
finally
push
the
new
commits.
</para>
<para>
The
housekeeping
we
need
to
do
entails
a
few
things.
If
this
is
a
big
new
feature
or
bug
fix,
we
should
be
documenting
this
in
the
ChangeLog
file
for
the
repository.
Please
follow
the
existing
convention
of
mentioning
the
contributor
as
well
as
the
issues
addressed
and
the
review
request
number.
Likewise,
if
this
is
someone's
first
contribution
you
will
need
to
add
them
to
the
COPYRIGHT
file
in
the
repository
as
well.
If
you
had
to
update
either
of
these
files,
review
your
changes
and
commit
them
directly.
</para>
<para>
Now
that
any
updates
to
ChangeLog
and
COPYRIGHT
are
completed,
we
can
actually
start
pushing
the
changes
back
to
the
canonical
repository.
Currently
not
all
of
the
canonical
repositories
are
publishing
repositories
so
we'll
need
to
manually
mark
the
commits
as
public.
This
is
easily
accomplished
with
<code>
hg
phase
--public
</code>
.
<emphasis>
Note
</emphasis>
,
if
you
are
not
using
a
separate
clone
of
the
canonical
repository
you
will
need
to
specify
a
revision
to
avoid
publishing
every
commit
in
your
repository.
If
you
run
into
issues
or
have
more
questions
about
phases
see
the
<ulink
url=
"https://www.mercurial-scm.org/wiki/Phases"
>
official
documentation
</ulink>
.
</para>
<para>
Now
that
the
changes
have
been
made
public,
we
can
finally
push
to
the
canonical
repository
with
<code>
hg
push
</code>
.
Once
that
is
done,
you'll
also
need
to
go
and
mark
the
review
request
as
<emphasis>
Submitted
</emphasis>
in
the
Review
Board
web
interface.
</para>
</sect2>
<sect2
id=
"patch"
>
<title>
Testing
Patches
Locally
</title>
<para>
If
you
want
to
test
a
patch
locally
for
any
reason,
you
first
need
to
make
sure
that
you
are
on
the
target
branch
for
the
review
request
which
is
listed
on
the
review
request
page.
In
most
cases
this
will
be
the
<emphasis>
default
</emphasis>
branch.
Regardless
you'll
need
to
run
<code>
hg
up
branch-name
</code>
before
applying
the
patch.
</para>
<para>
Now
that
you
are
on
the
correct
branch,
you
can
apply
the
patch
with
<code>
rbt
patch
#
</code>
where
<code>
#
</code>
is
the
id
of
the
review
request
you
want
to
test.
This
will
apply
the
patch
from
the
review
request
to
your
working
copy
without
committing
it.
</para>
<para>
Once
you're
done
with
your
testing
you
can
remove
the
changes
with
<code>
hg
revert
--no-backup
--all
</code>
.
This
will
return
your
repository
to
exactly
what
it
was
before
the
patch
was
applied.
The
<code>
--no-backup
</code>
argument
says
to
not
save
the
changes
that
you
are
reverting
and
the
<code>
--all
</code>
argument
tells
Mercurial
to
revert
all
files.
</para>
</sect2>
<sect2
id=
"cleanup"
>
<title>
Cleaning
up
a
Landed
or
Discarded
Review
Request
</title>
<para>
Whether
or
not
your
pull
request
has
been
accepted,
you
probably
want
to
clean
it
up
from
your
local
repository.
To
do
so,
you
need
to
update
to
a
branch
other
than
the
branch
you
built
it
on.
In
the
following
example,
we're
going
to
remove
the
branch
named
<emphasis>
my-new-branch-name
</emphasis>
that
we
used
to
create
a
review
request.
</para>
<programlisting>
hg
up
default
hg
prune
-r
'branch(my-new-branch-name)'
</programlisting>
<para>
Now,
all
commits
that
were
on
the
<emphasis>
my-new-branch-name
</emphasis>
branch
will
have
their
contents
removed
but
interally
Mercurial
keeps
track
that
these
revisions
have
been
deleted.
</para>
<para>
You
can
repeat
this
for
any
other
branches
you
need
to
clean
up,
and
you're
done!
</para>
</sect2>
</chapter>