From 8249fbfb602ea03ea67d9088cc4bdd8dfaf66066 Mon Sep 17 00:00:00 2001 From: Nicholas Marriott <nicholas.marriott@gmail.com> Date: Fri, 5 Oct 2012 09:05:44 +0100 Subject: [PATCH] Make some tweaks to NOTES and add a paragraph on git rather than huge PATCHES file. --- NOTES | 45 ++++++++--------- PATCHES | 153 -------------------------------------------------------- 2 files changed, 21 insertions(+), 177 deletions(-) delete mode 100644 PATCHES diff --git a/NOTES b/NOTES index 28bcce72..e8af37c3 100644 --- a/NOTES +++ b/NOTES @@ -5,9 +5,7 @@ to be accessed and controlled from a single terminal. tmux is intended to be a simple, modern, BSD-licensed alternative to programs such as GNU screen. This release runs on OpenBSD, FreeBSD, NetBSD, Linux and OS X and may still -run on Solaris and AIX (although they haven't been tested in a while). It is -usable, although there remain a number of missing features and some remaining -bugs are expected. +run on Solaris and AIX (although they haven't been tested in a while). If upgrading from 1.5, PLEASE NOTE: - The word-separators window option is now a session option. @@ -25,57 +23,56 @@ To build tmux from a release tarball, do: $ ./configure && make $ sudo make install -To build from a version control checkout, the configure script must be -generated by running: +To get and build the latest version control checkout: + $ git clone git://tmux.git.sourceforge.net/gitroot/tmux/tmux + $ cd tmux $ sh autogen.sh + $ ./configure && make -tmux consists of a server part and multiple clients. The server is created when -required and runs continuously unless killed by the user. Clients access the -server through a socket in /tmp. Multiple sessions may be created on a single -server and attached to a number of clients. Each session may then have a number -of windows and windows may be linked to a number of sessions. Commands are -available to create, rename and destroy windows and sessions; to attach and -detach sessions from client terminals; to set configuration options; to split -windows into several simultaneously displayed panes; and to bind and unbind -command keys (invoked preceded by a prefix key, by default ctrl-b). Please see -the tmux(1) man page for further information. +For more information see https://sourceforge.net/scm/?type=git&group_id=200378 +and http://git-scm.com. -A more extensive, but rough, todo list is included in the TODO file. +For documentation on using tmux, see the tmux.1 manpage. It can be viewed from +the source tree with: -tmux also depends on several features of the client terminal (TERM), if these -are missing it may refuse to run, or not behave correctly. + $ nroff -mdoc tmux.1|less + +Some common questions are answered in the FAQ file and a more extensive (but +slightly out of date) guide is available in the OpenBSD FAQ at +http://www.openbsd.org/faq/faq7.html#tmux. A rough todo list is in the TODO +file. A Vim syntax file is available in the examples directory. To install it: -- Drop the file in the syntax directory in your runtimepath (such as +- Drop the file in the syntax directory into runtimepath (such as ~/.vim/syntax/tmux.vim). - Make the filetype recognisable by adding the following to filetype.vim - in your runtimepath (~/.vim/filetype.vim): + (~/.vim/filetype.vim): augroup filetypedetect au BufNewFile,BufRead .tmux.conf*,tmux.conf* setf tmux augroup END -- Switch on syntax highlighting by adding "syntax enable" to your vimrc file. +- Switch on syntax highlighting by adding "syntax enable" to .vimrc. For debugging, running tmux with -v or -vv will generate server and client log files in the current directory. -tmux mailing lists are available; visit: +tmux mailing lists are available. The visit: https://sourceforge.net/mail/?group_id=200378 Bug reports, feature suggestions and especially code contributions are most welcome. Please send by email to: - nicm@users.sf.net + tmux-users@lists.sourceforge.net This file and the CHANGES, FAQ and TODO files are licensed under the ISC license. Files under examples/ remain copyright their authors unless otherwise stated in the file but permission has been received to distribute them with tmux. All other files have a license and copyright notice at their -start. Please contact me with any queries. +start. -- Nicholas Marriott <nicm@users.sf.net> diff --git a/PATCHES b/PATCHES deleted file mode 100644 index e1d3bf0d..00000000 --- a/PATCHES +++ /dev/null @@ -1,153 +0,0 @@ -Submitting Patches -================== - -Repository Overview -=================== - -The portable version of tmux uses git [1], a distributed revision control system. This -document is not intended to explain the git internals, for that there's -already a wealth of documentation on the Internet. - -The main portable tmux git repository [2] has one branch reflecting on-going -development: "master". Release points of tmux are tagged and are available -as git tags. - -When submitting a patch, the feature should be made on top of the -master branch. - -Preamble -======== - -If you've never used git before, git tracks meta-data about the committer -and the author, as part of a commit, hence: - -$ git config [--global] user.name "Your name" -$ git config [--global] user.email "you@example.com" - -Note that, if you already have this in the global ~/.gitconfig option, then -this will be used. Setting this per-repository would involve not using the -"--global" flag above. If you wish to use the same credentials always, -pass the "--global" option, as shown. - -This is a one-off operation once the repository has been cloned, assuming -this information has ever been set before. - -Coding style -============ - -Since tmux is inherently an OpenBSD project, please see the OpenBSD style(9) -guide: - -http://www.openbsd.org/cgi-bin/man.cgi?query=style&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html - -It is expected that patches to tmux honour this guideline. - -Use of topic branches -===================== - -Git's use of branches makes it very easy to separate out different topics -from one another -- hence, for any feature or patch developed, they should -be done in their own topic branch, which is branched from the current HEAD -of origin/master. Hence: - -$ git checkout master -$ git pull -$ git checkout my-new-feature - -Which at this point on means that you're on the "my-new-feature" branch, and -can then hack away. When you've got a series of changes, it's best to -consider how to commit them. Blindly doing: - -$ git commit -a - -which would commit all changes, won't make for a easy patch review, and will -likely just pollute the main git history with unnecessary noise. Not to -mention, if a bug is discovered, finding it in amongst a huge code commit -like that would be rather annoying. So instead, stage all the changes -you're doing logically together -- break up the feature into four or five -patches, or how ever many made sense. - -For example, if you were writing a new feature, you might have: - -* A patch to include any new header files. -* A patch for any new function prototypes. -* A patch per new function as it's written (or more, depending on the - complexity). - -This is nothing more than doing a: - -$ git add foo.h -$ git commit - -[Write commit message] - -... do some more hacking. - -$ git add main.c -$ git add utilities.c -$ git commit - -Working out what's changed -========================== - -Once you're happy with the commits on the "my-new-feature" branch, you'll -obviously want to check that they still work on top of any new code that -might have been committed to the master* branch since you creates the -"my-new-feature" branch. This is important as you'll be basing your patches -against that. Hence: - -$ git checkout master -$ git pull -$ git checkout my-new-feature - -(Note: It's conceivable here that the "my-new-feature" branch might undergo -rebasing against origin/master -- although that's not being mentioned -here in the general case, but would equally be acceptable.) - -Compiling/Testing patches -========================= - -Before you send patches to the mailing list, please ensure that you compile -tmux, as in the following: - -$ make clean && ./autogen.sh && ./configure && make - -This not only compiles with "-g" (for debug symbols), but also runs -some sanity check to ensure you've not missed anything. If you have, fix up -any warnings or errors, and repeat the above command until it's clean. - -Generating patches to send to the mailing list -============================================== - -So, you've been working hard on your new feature, all your changes are sat -in a local topic branch; "my-new-feature", and you want to submit them to -the list. You've already updated your copy of the master branch, and -your "my-new-feature" branch is checked-out, hence: - -$ git format-patch -M -n --cover-letter -o patch_store master - -Which will place a series of numbered commits in a directory called -"patch_store". These can then be sent to the list [3] using the -"git send-email" command. - -Note that if this is more a bug-fix, or a single patch, it's not always -necessary to generate a cover-letter -- so that option to "git format-patch" -can be elided if necessary, but it doesn't really matter. - -External hosting and pull-requests -================================== - -Alternatively, if using a hosted Git service [4], then it's acceptable -that a pull-request can be issued on a branch against a repository. - -Note that Thomas Adam has a Github repository [5] for tmux which is kept in -sync with the tmux repo on sourceforge. - -References -========== - -[1] http://git-scm.com -[2] https://sourceforge.net/scm/?type=git&group_id=200378 -[3] tmux-users@lists.sourceforge.net -[4] http://repo.or.cz -- or -- http://github.com -[5] https://github.com/ThomasAdam/tmux