From: Vladimir Panteleev Date: Mon, 11 Sep 2017 13:04:58 +0000 (+0000) Subject: docs/hacking-howto: Promote "Using git / sending patches" section X-Git-Tag: 4.15~97^2~2 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=5c693ec2ae124187cf5c0f05bcd1b55b1cdd5050;p=i3%2Fi3 docs/hacking-howto: Promote "Using git / sending patches" section Move the contents of the "Using git / sending patches" section to the top of the document. --- diff --git a/docs/hacking-howto b/docs/hacking-howto index 52436da6..6842ce81 100644 --- a/docs/hacking-howto +++ b/docs/hacking-howto @@ -8,6 +8,86 @@ touching i3’s source code. It should contain all important information to help you understand why things are like they are. If it does not mention something you find necessary, please do not hesitate to contact me. +== Using git / sending patches + +=== Introduction + +For a short introduction into using git, see +http://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy +or, for more documentation, see http://git-scm.com/documentation + +Please talk to us before working on new features to see whether they will be +accepted. A good way for this is to open an issue and asking for opinions on it. +Even for accepted features, this can be a good way to refine an idea upfront. However, +we don't want to see certain features in i3, e.g., switching window focus in an +Alt+Tab like way. + +When working on bugfixes, please make sure you mention that you are working on +it in the corresponding bug report at https://github.com/i3/i3/issues. In case +there is no bug report yet, please create one. + +After you are done, please submit your work for review as a pull request at +https://github.com/i3/i3. + +Do not send emails to the mailing list or any author directly, and don’t submit +them in the bugtracker, since all reviews should be done in public at +https://github.com/i3/i3. In order to make your review go as fast as possible, you +could have a look at previous reviews and see what the common mistakes are. + +=== Which branch to use? + +Work on i3 generally happens in two branches: “master” and “next” (the latter +being the default branch, the one that people get when they check out the git +repository). + +The contents of “master” are always stable. That is, it contains the source code +of the latest release, plus any bugfixes that were applied since that release. + +New features are only found in the “next” branch. Therefore, if you are working +on a new feature, use the “next” branch. If you are working on a bugfix, use the +“next” branch, too, but make sure your code also works on “master”. + +=== How to build? + +You can build i3 like you build any other software package which uses autotools. +Here’s a memory refresher: + + $ autoreconf -fi + $ mkdir -p build && cd build + $ ../configure + $ make -j8 + +(The autoreconf -fi step is unnecessary if you are building from a release tarball, + but shouldn’t hurt either.) + +==== Build system features + +* We use the AX_ENABLE_BUILDDIR macro to enforce builds happening in a separate + directory. This is a prerequisite for the AX_EXTEND_SRCDIR macro and building + in a separate directory is common practice anyway. In case this causes any + trouble when packaging i3 for your distribution, please open an issue. + +* “make check” runs the i3 testsuite. See docs/testsuite for details. + +* “make distcheck” (runs testsuite on “make dist” result, tiny bit quicker + feedback cycle than waiting for the travis build to catch the issue). + +* “make uninstall” (occasionally requested by users who compile from source) + +* “make” will build manpages/docs by default if the tools are installed. + Conversely, manpages/docs are not tried to be built for users who don’t want + to install all these dependencies to get started hacking on i3. + +* non-release builds will enable address sanitizer by default. Use the + --disable-sanitizers configure option to turn off all sanitizers, and see + --help for available sanitizers. + +* Support for pre-compiled headers (PCH) has been dropped for now in the + interest of simplicity. If you need support for PCH, please open an issue. + +* Coverage reports are now generated using “make check-code-coverage”, which + requires specifying --enable-code-coverage when calling configure. + == Window Managers A window manager is not necessarily needed to run X, but it is usually used in @@ -951,86 +1031,6 @@ Without much ado, here is the list of cases which need to be considered: not relative to workspace boundaries, so you must correct their coordinates or those containers will show up in the wrong workspace or not at all. -== Using git / sending patches - -=== Introduction - -For a short introduction into using git, see -http://web.archive.org/web/20121024222556/http://www.spheredev.org/wiki/Git_for_the_lazy -or, for more documentation, see http://git-scm.com/documentation - -Please talk to us before working on new features to see whether they will be -accepted. A good way for this is to open an issue and asking for opinions on it. -Even for accepted features, this can be a good way to refine an idea upfront. However, -we don't want to see certain features in i3, e.g., switching window focus in an -Alt+Tab like way. - -When working on bugfixes, please make sure you mention that you are working on -it in the corresponding bug report at https://github.com/i3/i3/issues. In case -there is no bug report yet, please create one. - -After you are done, please submit your work for review as a pull request at -https://github.com/i3/i3. - -Do not send emails to the mailing list or any author directly, and don’t submit -them in the bugtracker, since all reviews should be done in public at -https://github.com/i3/i3. In order to make your review go as fast as possible, you -could have a look at previous reviews and see what the common mistakes are. - -=== Which branch to use? - -Work on i3 generally happens in two branches: “master” and “next” (the latter -being the default branch, the one that people get when they check out the git -repository). - -The contents of “master” are always stable. That is, it contains the source code -of the latest release, plus any bugfixes that were applied since that release. - -New features are only found in the “next” branch. Therefore, if you are working -on a new feature, use the “next” branch. If you are working on a bugfix, use the -“next” branch, too, but make sure your code also works on “master”. - -=== How to build? - -You can build i3 like you build any other software package which uses autotools. -Here’s a memory refresher: - - $ autoreconf -fi - $ mkdir -p build && cd build - $ ../configure - $ make -j8 - -(The autoreconf -fi step is unnecessary if you are building from a release tarball, - but shouldn’t hurt either.) - -==== Build system features - -* We use the AX_ENABLE_BUILDDIR macro to enforce builds happening in a separate - directory. This is a prerequisite for the AX_EXTEND_SRCDIR macro and building - in a separate directory is common practice anyway. In case this causes any - trouble when packaging i3 for your distribution, please open an issue. - -* “make check” runs the i3 testsuite. See docs/testsuite for details. - -* “make distcheck” (runs testsuite on “make dist” result, tiny bit quicker - feedback cycle than waiting for the travis build to catch the issue). - -* “make uninstall” (occasionally requested by users who compile from source) - -* “make” will build manpages/docs by default if the tools are installed. - Conversely, manpages/docs are not tried to be built for users who don’t want - to install all these dependencies to get started hacking on i3. - -* non-release builds will enable address sanitizer by default. Use the - --disable-sanitizers configure option to turn off all sanitizers, and see - --help for available sanitizers. - -* Support for pre-compiled headers (PCH) has been dropped for now in the - interest of simplicity. If you need support for PCH, please open an issue. - -* Coverage reports are now generated using “make check-code-coverage”, which - requires specifying --enable-code-coverage when calling configure. - == Thought experiments In this section, we collect thought experiments, so that we don’t forget our