* Don't commit directly, instead make a pull request on GitHub.


Building from git
-----------------

To build from git, or without relying on the generated files in a source
release, automake, autoconf, libtool, pkg-config and git must be installed.

(Note, the exact packages needed for certain distros may be found in
.travis.yml and appveyor.yml.)

Run

./bootstrap && ./configure --enable-relocatable

to set up and configure the source tree; optional configure arguments can be
supplied as normal.

See INSTALL (which is created by bootstrap) for instructions from this point
on.


Working in libenchant
---------------------

   When writing libenchant our priorities are

	1) Portable
	2) Maintainable & Documented
	3) Modular and well designed

    When you submit code for inclusion in libenchant, please keep those
things in mind.  While performance is important please note that
well-designed algorithms and data structures are fertile areas for
development; obfuscated code to make a loop 3% faster is not.  Specifically,
this means:

	- Clarity of design and function are paramount
	- Make sure your code does not generate warnings
	- Please follow the formatting style


Formatting style
----------------

   The formatting style of libenchant is a mix of various styles.  Please
familiarise yourself with the GNU coding standards (shipped with most
GNU/Linux systems as the standards.info file), then read the Linux
kernel coding standards and ignore Linus's jokes.  Then look at the
Gtk+ header files to get acquainted with how to write nice header files
that are almost self documenting.

   Emacs users should use the supplied .dir-locals.el.

   Remember: Use tabs for indentation: that will keep your
code honest as you will be forced to split your routines into more
modular chunks (as detailed by Linus). 
   
   On top of that, please:

	- Follow the Gtk+ cleanliness conventions for function
	  prototypes.

	- Follow the Gtk+ namespace convention for function names:
	  module_submodule_operation

	- Every entry point to a public routine should use the
	  g_return_if_fail and g_return_val_if_fail macros to verify
	  that the parameters passed are valid.

	- Under no circumstances use magic variables.  Use typedef
	  enum { ... } type; to create enumerations.  Do not use
	  integers to hold enumeration values: the compiler can help
	  catch various errors.

	- Use g_warning to mark spots that need to be reviewed or are
	  not finished.

	- Do not submit code that is just a temporary workaround for a
	  full fledged feature.  We do not want to maintain limited
	  features.  It is better to submit an implementation designed
	  to be expanded and enhanced, even if it is not completely
	  finished.

	- Follow the libenchant commenting style, which is not the Gtk
	  style;
		/* ie. use this for
		 * multi-line comments
		 */

   All of this is to ensure the libenchant code will be kept within
reasonable margins of maintainability for the future: Remember, in two years
you will probably be far too busy to maintain your own contributions, and they
might become a burden to the program maintainers.

   libenchant is intended to be a foundation for a various document-centric
projects.

   Cleaning code in libenchant is more important than trying not to break
existing code.  Code clean-ups are always welcome.


API documentation
-----------------

To generate API documentation, simply run

doxygen

and see doxygen/html/index.html in a web browser.


Making a release
----------------

To make a release, you'll need woger:

https://github.com/rrthomas/woger

and github-release, suitably configured:

https://github.com/aktau/github-release

Having tested and pushed all the changes, update the version number in
configure.ac and write the NEWS entry and push those too.

Then execute:

make release