diff options
Diffstat (limited to 'PATCHES')
| -rw-r--r-- | PATCHES | 153 |
1 files changed, 0 insertions, 153 deletions
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 |