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.
This commit is contained in:
Vladimir Panteleev
parent
0f2bce3916
commit
5c693ec2ae
|
|
@ -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 understand why things are like they are. If it does not mention something
|
||||||
you find necessary, please do not hesitate to contact me.
|
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
|
== Window Managers
|
||||||
|
|
||||||
A window manager is not necessarily needed to run X, but it is usually used in
|
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
|
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.
|
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
|
== Thought experiments
|
||||||
|
|
||||||
In this section, we collect thought experiments, so that we don’t forget our
|
In this section, we collect thought experiments, so that we don’t forget our
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue