develop.txt

Vim Development
===============

Vim source code repository is on hosted on Github:

    https://github.com/vim/vim

Apart from Github, development also happens on the vim-dev maillist with people
contributing patches via email. Subscribe if you want to get involved, see
[here](maillist.php#vim-dev).

To see known bugs and next things to work on, use Vim help:

    :help todo

The issue tracker is [here](https://github.com/vim/vim/issues).

Making changes to Vim
=====================

Let's say you want to make a bugfix, small correction or develop a new feature
for Vim.

Vim source code is hosted at github.com and managed by git. Using git is
preferred for developing and bugfixing Vim.

If you are new to Git, here's the recommended resource to get familiarized with
it:

    http://git-scm.com/book/en/v2

Installing git
--------------

To install git:

- on Debian (or Ubuntu) use `$ apt-get install git`
- on OS X install [Homebrew](http://brew.sh) and then use `$ brew install git`
- on Windows install [msysgit](http://msysgit.github.io)

1. Clone the repository
=======================

Clone Vim repository into `vim/` directory in the current path:

    $ git clone https://github.com/vim/vim
    $ cd vim

You can now browse and see Vim's source code.

2. Create changes
=================

It's now time to make changes to the source code. Here's the workflow to
make this:

- pull the latest changes from Vim remote repository

      $ git checkout master
      $ git pull

- create a new branch in local git repository

      $ git checkout -b fix_annoying_bug

- make changes to the source code

- commit the changes

      $ git add changed/file.xyz
      $ git commit

When writing a commit message, keep the first line short, up to 50 characters
or less. Add more details about the change in the commit message body.

When the feature/bugfix is done, you're ready for the next step: submitting the
change for review and evaluation for merging into Vim's source code.

Depending on your preferences submitting a change can be done in 2 ways:

- by creating and opening a pull request to Vim's main repository via Github
- by creating patch and sending it to vim-dev maillist

2.1 Open a pull request
=======================

A simple way of proposing a change to Vim's source code is opening a pull
request via Github.

- create a Github account, if you don't have it already

- Fork the Vim repository by going to https://github.com/vim/vim and clicking
  "Fork" in the upper right corner of the page.
  This creates a copy of Vim's repository for your Github account, example:
  https://github.com/username/vim

- locally, add the forked repository as a git remote

      $ git remote add fork https://github.com/username/vim

- push your local branch 'fix_annoying_bug' to the forked repository

      $ git push -u fork fix_annoying_bug

- In a browser navigate to forked repo https://github.com/username/vim
  and open a pull request to main Vim repository. Make sure you write a good
  description of your change in the pull request message.

Now, it's up to Vim's maintainer to review, comment and consider merging your
change into the main repository.

2.2 Create a patch
==================

Another way of submitting changes is by creating a patch and sending it to the
vim-dev maillist. This way you don't have to have a Github account and steps in
'2.1 Open a pull request' should be skipped.

Here's what you do, continuing from steps described in '2. Create changes':

- create a patch file from your changes using git

      $ git format-patch master --stdout > fix_annoying_bug.patch

- send the patch file 'fix_annoying_bug.patch' to the vim-dev list.

Other Vim developers and Vim's maintainer will review, comment and consider
merging your change into the main repository.

Before submitting your change
=============================

A few suggestions to help have your pull request or patch be easily accepted:

- Make sure your change actually works

- The code should be readable

- Simple things first, don't try to fix everything in one single patch/pull
  request but rather create several small patches (This allows for easier
  review)

- Make sure all the tests still pass (make test) and if possible add new tests
  for your feature/bugfix (look into src/testdir directory for existing tests
  and extend them if possible). For newly created testfiles, give it meaningful
  names.

- Try hard not to break anything (compile with different features, test, watch
  out for warnings (uncomment #FLAGS = -g -DDEBUG -Wall -Wshadow
  -Wmissing-prototypes in the src directory Makefile).

- Test your changes by running under valgrind and make sure it doesn't leak memory.

- Document your changes (also update the runtime documentation that comes with
  Vim and any related vim script e.g. optwin.vim, syntax or filetype plugins).

- Try to follow the advices given in develop.txt (:h develop.txt)

- Come up with a good usecase for your new feature (e.g. make Bram want to
  include your feature ;))

- If possible try not to introduce new options ;)

After submitting your change
============================

- When you submit your patch/pull request and don't get immediate feedback,
  don't despair. Bram is overloaded with work so just be patient. Usually your
  patch will be included into the todo list (:h todo.txt) and will be included
  into Vim eventually.

- Respond to feedback and try to fix all mentioned issues. Beware, discussions
  might wander away from your original topic you originally addressed, don't let
  that scare you away!

- While your code submission is pending, regularly pull updates from Vim main
  repository to your local master branch. Keep your feature branch rebased and
  fix conflicts that may occur.
  After a reasonable time, if you sent a patch to the vim-dev maillist resend
  your resynced patch again.

If you have suggestions for improvement of this page please send a message to
the vim-dev maillist.

git.txt

The Vim Git repository
======================

Vim source code repository is hosted on Github:

    https://github.com/vim/vim

This is where the most recent versions of the files, including runtime files are
kept.

This guide explains the most straightforward way to get Vim source code and keep
it up-to-date using Git.

If you are new to Git, here's the recommended resource to get familiarized with
it:

    http://git-scm.com/book/en/v2

Installing git
--------------

To get Vim source code locally, you'll need to use Git. Here are the options for
installing Git:

- on Debian (or Ubuntu) use `$ apt-get install git`
- on OS X install [Homebrew](http://brew.sh) and then use `$ brew install git`
- on Windows install [msysgit](http://msysgit.github.io)

Fetching the full source code
-----------------------------

You can get Vim for the first time by cloning the repository:

    $ git clone https://github.com/vim/vim

That will clone full git repository to `vim/` directory in the current path.

Updates are continually added to Vim repository by the maintainer. Here's how
you fetch the latest changes:

    $ cd vim
    $ git pull

Fetching the source code without history
----------------------------------------

The recommended steps to fetch a repository are described in
'Fetching the full source code'.

However, if you have bandwidth limitations you can do "shallow clone". The
benefits are faster clone and reduced bandwidth usage.
The downside is that you don't have full git history of the repository.

Here's the command for fetching Vim source code using "shallow clone":

    $ git clone --depth 1 https://github.com/vim/vim

Build and install Vim
---------------------

Build and install Vim as usual. If you are happy with the defaults:

    $ cd src
    $ make distclean  # if you built Vim before
    $ make
    $ sudo make install

Vim source code branches
------------------------

The "master" branch is the main code branch. Apart from "master", other branches
are:

- "vim73" branch was for 7.3 test versions
- "vim72" branch is for the older 7.2.xxx versions. No further changes are
  expected there.

When browsing source code locally, you probably want to switch to the "master"
branch to fetch the latest updates. You do that like this:

    $ git checkout master
    $ git pull

If you made changes to your local Vim repository `$ git pull` command
might fail (because of conflicts). If that happens and you just want to discard
your local changes, use:

    $ git checkout -- .

And then pull the latest changes again:

    $ git pull

mercurial.txt

The Vim repository using Mercurial
==================================

Vim is hosted on Github and available through Mercurial using the
[hg-git](http://hg-git.github.io) plugin.

Installing hg-git
-----------------

All the installation instructions can be found on the official
[hg-git webpage](http://hg-git.github.io).

In short, the steps are:

    $ easy_install hg-git

If you don't have `easy_install` available, you can get it as a part of Python's
[setuptools](https://pypi.python.org/pypi/setuptools) package.

Next, make sure the following is added to `~/.hgrc`:

    [extensions]
    hgext.bookmarks =
    hggit =

Fetching the source code
------------------------

You can obtain Vim for the first time with:

    $ hg clone git+https://github.com/vim/vim

That will clone full git repository to `vim/` directory in the current path.

Update to the latest version can be done with:

    $ cd vim
    $ hg pull
    $ hg update

If you don't know how to use Mercurial, you'll probably want to look at the
[Guide](http://mercurial.selenic.com/guide).

Build and install Vim as usual. If you are happy with the defaults:

    $ cd src
    $ make distclean  # if you built Vim before
    $ make
    $ sudo make install

You can browse the git repository [online](https://github.com/vim/vim).
This shows the most recent version of the files, including runtime files.

Note that besides the "default" branch there are others. The "vim73" branch was
for 7.3 test versions. You probably want to switch to the "default" branch to
get 7.3.001 and later, like this:

    $ hg update default

The "vim72" branch is for the older 7.2.xxx versions. No further changes are
expected here.

If you have local changes you may need to merge. If you are sure you can discard
local changes (e.g. if you were just trying a patch), you can use:

    $ hg update -C