<?xml version="1.0" encoding="UTF-8"?>
<article id="Introduction">
  <title>Introduction to WinMerge</title>

  <para>WinMerge is an <ulink url="https://opensource.org/">Open
  Source</ulink> differencing and merging tool for Windows. WinMerge can compare
  both folders and files, presenting differences in a visual text format that is
  easy to understand and handle.</para>

  <para>WinMerge is highly useful for determining what has changed between
  project versions, and then merging changes between versions. WinMerge can be
  used as an external differencing/merging tool or as a standalone
  application.</para>

  <para>In addition, WinMerge has many helpful supporting features that make
  comparing, synchronising, and merging as easy and useful as possible. Several
  programming languages and other file formats are syntax-highlighted.</para>

  <para>WinMerge is not a hex editor. WinMerge can show binary files contents
  and differences between them. But the information is meant for viewing only:
  editing binary files with WinMerge can break the files.</para>

  <para>The goal of WinMerge development is to make comparing, synchronizing,
  and merging folders and files easy and fast, while maintaining maximum
  reliability. Ease of use is of key importance for reducing errors. The latest
  version, &WinMergeVersion; is
  considered a stable and reliable program to use.</para>

  <para>Please note that WinMerge is not freeware (as many sites on the Web have
  stated): it is <ulink
  url="https://www.gnu.org/licenses/gpl-2.0.html">GPL</ulink> licensed. We
  provide you with a good tool for free, so please honor your license agreement
  and submit improvements to us. We are happy to get help improving WinMerge, to
  the advantage of all WinMerge users.</para>

  <section>
    <title>WinMerge versions<indexterm>
        <primary>WinMerge versions</primary>
      </indexterm></title>

    <para>There are three kind of versions available in the <ulink
    url="https://sourceforge.net/projects/winmerge/files/">downloads</ulink>
    page.</para>

    <section>
      <title><indexterm>
          <primary>stable WinMerge versions</primary>
        </indexterm>Stable versions</title>

      <para><ulink
      url="https://sourceforge.net/projects/winmerge/files/stable/">Stable
      versions</ulink> are recommended for most users. If you are unsure about
      what version to use, use the latest stable version. Stable versions have
      an even last number, for example, 2.14.0, 2.16.2 and 2.16.4.</para>
    </section>

    <section>
      <title><indexterm>
          <primary>beta WinMerge versions</primary>
        </indexterm>Beta versions</title>

      <para><ulink
      url="https://sourceforge.net/projects/winmerge/files/beta/">Beta
      versions</ulink> are for people who want to test latest features and
      improvements made after last stable version. Beta versions are not tested
      as extensively as stable versions and probably have some bugs. Beta
      versions have an odd last number, for example 2.16.3 and 2.16.5. Beta versions
      can be used in production, because they are not expected to have major
      bugs. But there is always a risk with using beta-level releases, so
      consider it carefully. We have tried to release a new stable series once a
      year, so it may be worth waiting for few months for the next stable
      release...</para>
    </section>

    <section>
      <title><indexterm>
          <primary>experimental WinMerge versions</primary>
        </indexterm>Experimental versions</title>

      <para><ulink
      url="https://sourceforge.net/projects/winmerge/files/alpha/">Experimental
      versions</ulink> or alpha versions are snapshot releases from our version control system
      (Subversion). They have all the latest features and improvements. Some
      features may still be buggy or incomplete. These releases are made
      available to allow users to try out the current code without needing to
      compile, and to participate in development discussions concerning new and
      changing features. We also appreciate any help testing the current code.
      Use experimental versions with care and enable backups! And please <ulink
      url="https://github.com/WinMerge/winmerge/issues">report
      bugs</ulink> that you find while using these builds: it really helps with
      WinMerge development!</para>
    </section>

    <section>
      <title>Version tree</title>

      <para>All this talk about different versions might be confusing if you
      never have worked with this kind of model. Lets illustrate with a
      picture:</para>

      <para><mediaobject>
          <imageobject>
            <imagedata fileref="art/WinMerge_versions.png" format="PNG" />
          </imageobject>

          <caption><para> WinMerge stable and development
          versions</para></caption>
        </mediaobject>The preceding diagram shows the relationships between
      different releases and versions. Development always happens within
      experimental and beta development versions. At the appropriate points we
      create new branches for stable releases. In the diagram, the arrows for
      2.4.x and 2.6.x versions are two current stable branches. (The diagram is
      a snapshot; it is not updated to show the current stable branch).</para>

      <important>
        <para>A branch always indicates a separate development effort. There is
        no any automation to copy improvements or fixes from development
        versions to stable versions, or in the opposite direction. Changes are
        always selected by hand and then merged (using WinMerge, of
        course).</para>
      </important>

      <para>After a branch is created, we try to keep the code in it as stable
      as possible. Usually this means that we copy only tested bug fixes from
      development versions to stable versions. Unfortunately this is not always
      an easy task, and errors can occur. New bugs can also appear in stable
      versions: this is real-life software development. However, in general,
      quality increases in branches. For example, 2.6.14 was a better release
      than 2.4.0. So we always recommend using the latest stable branch
      release.</para>

      <para>This branching also means that stable versions don't get many new
      features after a branch is created. Stable versions 2.6.0 and 2.6.14 had
      pretty similar features. After the 2.6 stable branch, we created a new
      stable branch, 2.8, where we added many improvements and fixes.</para>

      <para>Many software vendors always increase their version numbers and
      advise people to use the version with the biggest number. If WinMerge were
      developed as proprietary software, users would see only versions from
      stable branches. But because WinMerge is an open source software project,
      we want to keep our development as open as possible and to release many
      development versions. The latest development version can have version
      number 2.9.1.0 and the latest stable version can be version 2.6.14.</para>
    </section>
  </section>

  <section>
    <title><indexterm>
        <primary>WinMerge support</primary>

        <secondary>reporting bugs</secondary>
      </indexterm>Getting support and reporting bugs</title>

    <para>The <ulink
    url="https://forums.winmerge.org/viewforum.php?f=4">Open
    Discussion forum</ulink> is the fastest way to get help. Please be patient,
    it may take some time for somebody to answer.</para>

    <para>If you find a bug, please submit it as a <ulink
    url="https://github.com/WinMerge/winmerge/issues">bug
    report</ulink>. Please attach as much information as you can: at a minimum,
    the version number of WinMerge that you are using. If you can, also attach a
    configuration log which, you can display by clicking <menuchoice>
        <guimenu>Help</guimenu>

        <guimenuitem>Configuration</guimenuitem>
      </menuchoice> in the WinMerge window. Good information in a bug report
    makes it more likely that your bug will be fixed quickly.</para>

    <important>
      <para>Include the version number in bug reports. You can check the version
      number by clicking <menuchoice>
          <guimenu>Help</guimenu>

          <guimenuitem>About WinMerge</guimenuitem>
        </menuchoice>.</para>
    </important>
  </section>

  <section>
    <title><indexterm>
        <primary>WinMerge development</primary>
      </indexterm>WinMerge source code and development</title>

    <para>WinMerge source code is available in the <ulink
    url="https://sourceforge.net/projects/winmerge/files/">downloads</ulink>
    page and from the
    <ulink url="https://github.com/winmerge/">GitHub</ulink> project pages.
    Anyone can download the sources, study them, and alter them.
    If you find (and fix) bugs, improve something, and so on, please submit your
    changes to us as patches or pull requests  and help improve this product!
    If you publish your altered version, you are
    required to publish the changes to source code too. This is what the <ulink
    url="https://www.gnu.org/licenses/gpl-2.0.html">GPL</ulink> license is about:
    please respect it.</para>

    <para>WinMerge development work is done by people in their spare time. 
	Nobody gets paid for
    improving WinMerge. We try to fix bugs as we find them or when somebody
    reports them to us. We really try - we use WinMerge too. But there are
    absolutely no promises for new features. We always appreciate any help with
    WinMerge, be it testing, documenting, translating, or coding.</para>
  </section>
</article>
