nixo
/
gri3-wm
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge pull request #2928 from CyberShadow/pull-20170911-130032 

docs/hacking-howto: Promote "Using git / sending patches" section
This commit is contained in:
Ingo Bürk 2017-09-11 20:49:47 +02:00 committed by GitHub
parent 0f2bce3916 7116bbaa12
commit 5e5444613f
1 changed files with 78 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
docs/hacking-howto
View File

@ -8,6 +8,84 @@ 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.
== Building i3
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.
== Using git / sending patches
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”.
== Window Managers
A window manager is not necessarily needed to run X, but it is usually used in
@ -951,86 +1029,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