Hi all,
in "Preparations for moving to github" thread Bram said it would be a good idea
to update the following pages:
- http://www.vim.org/develop.php
- http://www.vim.org/mercurial.php
And also create a new page with instructions for git. I went ahead and created
a change proposal for these.
The files are in the attachment.
If you don't want to download the files, you can read the content here:
https://gist.github.com/bruno-/19c76f204a901441ad65
The "develop.txt" and "mercurial.txt" contain changes for existing pages.
"git.txt" contains instructions for fetching the source code with git and
building/installing vim.
The files are in plain txt format, let me know if some other format is needed.
Feedback is welcome!
Bruno
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
For more options, visit https://groups.google.com/d/optout.
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.
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
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
