Differences between revisions 15 and 16
Revision 15 as of 2014-03-28 12:34:37
Size: 10057
Editor: andywenk
Comment: add cwiki
Revision 16 as of 2014-04-20 11:26:20
Size: 10518
Editor: andywenk
Comment: add info for irc proxy bip
Deletions are marked like this. Additions are marked like this.
Line 306: Line 306:
=== IRC proxy ===

If you are using a client like Textual or XChat, you will likely loose conversations when you're offline. To avoid this, you can use a IRC proxy.
The idea is to not connect directly to the IRC server but through the proxy set up on a server you have. The irc proxy will be connected all the time and
log all the conversations in channels you are subscribed. One easy to install and configure IRC proxy is http://bip.milkypond.org/ .

The official documentation has moved to http://docs.couchdb.org — The transition is not 100% complete, but http://docs.couchdb.org should be seen as having the latest info. In some cases, the wiki still has some more or older info on certain topics inside CouchDB.

You need to be added to the ContributorsGroup to edit the wiki. But don't worry! Just email any Mailing List or grab us on IRC and let us know your user name.

Committer First Steps

@@ WIP

Introduction

Beeing a new committer requires to do a whole bunch of steps before the work on CouchDB can start. This document describes many of these tasks and should help to get things working. If there are any questions, please ask on IRC #couchdb-dev or use the dev@couchdb.apache.org mailinglist.

Note: the command line examples have been run on Mac OS X but should be easily adapted to other Unix like systems

First Read

Before you start, please read the info found on these pages:

http://wiki.apache.org/couchdb/Community_Guide

http://www.apache.org/dev/new-committers-guide.html

http://www.apache.org/dev/committers.html

svn checkout https://svn.apache.org/repos/private/committers and read the docs (see 1. setup svn)

Setup svn

http://www.apache.org/dev/version-control.html

Create a pgp key ring with gnupg

How to generate a gnupg key and a fingerprint?

URL: http://www.gnupg.de/gph/en/manual.html

Install gnupg2

brew install gnupg2

Create a keypair

It should be a RSA key with at minimum 4096 bits, avoiding SHA-1. See https://www.apache.org/dev/openpgp.html#sha1 for instructions on the latter.

gpg2 --gen-key

The result is something like this:

pub   4096R/1ED29548 2013-11-06
Key fingerprint = AB44 8542 1E12 1333 4FEC  9452 B65D 6BE3 9ED3 9588
uid                     Your Name (CouchDB) <your.name@apache.org>
sub   4096R/A62334BF 2013-11-06

Create a revocation certificate

gpg2 --output revoke.asc --gen-revoke your.name@apache.org

Show existing keys

gpg2 --list-keys

Export key

gpg2 --armor --export your.name@apache.org

The output is something like this:

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG/MacGPG2 v2.0.19 (Darwin)
Comment: GPGTools - http://gpgtools.org

mQINBFJ6txIBEADHomX4Q+T/GToy3g/goh0EjbfA+bYnJJce1PLKU3zvXXtQeTfA
[veeery long letter salad]
-----END PGP PUBLIC KEY BLOCK-----

Upload your public key to the MIT pgp-key-server

There are many public key servers available. The one preferred by the ASF is: http://pgp.mit.edu Simply paste your public key there and submit the form. When done so, search for your name and find your key.

Your key will be added

Your key will be added, when you inserted the key fingerprint at https://id.apache.org/. You will then find your key here: https://people.apache.org/keys/committer/

Setup your ASF id

This is an important step and you should do it now. Jump to this page https://id.apache.org/ and

Create a FOAF file

This is an optional step. The ASF is using this file format (XML) to make informations about you available. Jump to this page and fill the form http://people.apache.org/foaf/foafamatic.html. When done follow these steps:

Create an Jenkins account

The Apache CouchDB project is using Jenkins for continuous integration. Create an account here and http://ci.couchdb.org:8888/ and ping Jan Lehnardt afterwards

Create an pootle account

For L10N, the Apache CouchDB project is using the translation service from the ASF. Please create an account at

https://translate.apache.org/accounts/login/?next=%2Fprojects%2FCouchDB%2F

Please use your ASF username and password. The account will be created automatically.

Create an JIRA account

For tickets, JIRA is used. Please jump to https://issues.apache.org/jira/browse/COUCHDB and create an account.

Create an Wiki account

Many information are located in a Wiki at https://wiki.apache.org/couchdb and also in the new wiki found at https://cwiki.apache.org/confluence/display/COUCHDB/Apache+CouchDB+Home. Please jump there and create an account.

Please add your name and a short description to the Committers page her in the wiki.

Git

The source code of the Apache CouchDB project is versioned with git.

Git info

At

http://wiki.apache.org/couchdb/SourceCode

https://git-wip-us.apache.org/#committers-getting-started

you will find many informations regarding git. Please read this carefully.

Git source code repository

The source code of Apache CouchDB can be found here:

https://git-wip-us.apache.org/repos/asf/couchdb.git

The complete list of all CouchDB git repositories can be found here:

https://git-wip-us.apache.org/repos/asf?s=couchdb

Git guidelines

Here is a proposed workflow for git. Please follow these guidelines.

  • create a feature branch for bigger changes or tasks or tickets. If it is a ticket the feature branch should be named like: 1912-troubleshooting-guide where 1912 is the ticket number and "Troubleshooting guide" the title of the ticket
  • please follow these steps for your work:
    • create feature branch from master
    • work on feature branch
    • clean up feature branch commits
    • rebase feature branch onto current master
    • merge feature branch into master
  • where "clean up" means:
    • clean up whitespace in code area
  • rebase your work into logical steps - this results in the following single commits
    • minimally complete refactoring #1
    • minimally complete refactoring #2
    • minimally complete refactoring #3
    • actual feature/fix, part #1
    • actual feature/fix, part #2

Commit message note: The first line of the commit message should not be longer than around 60 letters followed by a newline. This avoids breaking commit emails and ugly git logs.

Git configuration

This is how your git config file in the project should look like

.git/config

[core]
        repositoryformatversion = 0
        filemode = true
        bare = false
        logallrefupdates = true
        ignorecase = true
        precomposeunicode = false
[remote "origin"]
        url = https://git-wip-us.apache.org/repos/asf/couchdb.git
        fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
        remote = origin
        merge = refs/heads/master
[user]
        name = Andy Wenk
        email = andywenk@apache.org
[credential]
        helper = osxkeychain

Because you don’t want to write your credentials for the git repository each time, you want to cache your password. Please follow these instructions:

https://help.github.com/articles/set-up-git#password-caching

You may not want to add the user.name, user.email and credential.helper globally but only to the current repository. In this case simply run:

git config user.name "your username"
git config user.email "your.name@apache.org"
git config credential.helper osxkeychain

To get things working here, you have to setup a .netrc file (or extend an existing) in your home directory with the following content:

~/.netrc

machine git-wip-us.apache.org
login <your_asf_username>
password *********

Showing your Contributions

If you want your contributions to CouchDB to show up on your GitHub profile, you have to star each of the repositories due to the way GitHub mechanics work for repo mirrors.

To do that you can find them all here: https://github.com/apache

You can also show your affiliation with Apache by adding yourself to the following file available through subversion:

svn co https://svn.apache.org/repos/private/committers/docs/github_team.txt

Then politely let infra know and your profile should show up at: https://github.com/apache?tab=members

locale settings

If you have problems building CouchDB, check if your local settings are correct:

locale
LANG="en_US.UTF-8"
LC_COLLATE="en_US.UTF-8"
LC_CTYPE="en_US.UTF-8"
LC_MESSAGES="en_US.UTF-8"
LC_MONETARY="en_US.UTF-8"
LC_NUMERIC="en_US.UTF-8"
LC_TIME="en_US.UTF-8"
LC_ALL="en_US.UTF-8"

If LANG is empty, add this to your ~/.bash_profile:

export LC_ALL=en_US.UTF-8  
export LANG=en_US.UTF-8

project site: http://couchdb.apache.org documentation: http://docs.couchdb.org translation service:

Mailing-lists

subscribe to all CouchDB lists http://couchdb.apache.org/#mailing-lists

Info: no attachments are allowed beside zip files

Note when using GMail

there are some known issues when you are using GMail and want to integrate your Apache email address into GMail. Please read the configuration provided at http://www.apache.org/dev/user-email.html#configure. You can use your apache.org email address for the mailing-lists but you are not required to (committer level).

IRC

Very much of the discussions in all areas are held in the IRC channels. Here is the info to set things up:

/msg NickServ register <a_password> <your_email>

in preferences set start command:

/msg NickServ identify <your_password>

IRC proxy

If you are using a client like Textual or XChat, you will likely loose conversations when you're offline. To avoid this, you can use a IRC proxy. The idea is to not connect directly to the IRC server but through the proxy set up on a server you have. The irc proxy will be connected all the time and log all the conversations in channels you are subscribed. One easy to install and configure IRC proxy is http://bip.milkypond.org/ .

Tools

While developing CouchDB or applications based on CouchDB, it's good to have some tools available. Here is a list with the intention to be extended:

HTTP / TCP

Committer_First_Steps (last edited 2014-04-20 11:26:20 by andywenk)