#LyX 2.1 created this file. For more info see http://www.lyx.org/
-\lyxformat 470
+\lyxformat 474
\begin_document
\begin_header
\textclass scrbook
\pdf_keywords "LyX, Documentation, Development"
\pdf_bookmarks true
\pdf_bookmarksnumbered true
-\pdf_bookmarksopen false
+\pdf_bookmarksopen true
\pdf_bookmarksopenlevel 1
\pdf_breaklinks false
\pdf_pdfborder false
\use_package stmaryrd 0
\use_package undertilde 0
\cite_engine basic
-\cite_engine_type numerical
+\cite_engine_type default
\biblio_style plain
\use_bibtopic false
\use_indices false
\end_layout
\begin_layout Subtitle
-Version 2.1.x
+Version 2.2.x
\end_layout
\begin_layout Author
\begin_layout Section
When is an update of the .lyx file format number needed?
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:When-is-an"
+
+\end_inset
+
+
\end_layout
\begin_layout Standard
-When you ware working on a new feature you may ask yourself whether it needs
+When you are working on a new feature you may ask yourself whether it needs
an update of the .lyx file format number.
Whether an update is needed or not is not always obvious.
Below you can find a list of reasons for file format updates with explanations:
setting Whenever you introduce a new setting that is stored in the document
header, a file format update is needed.
This is also true if you add a new valid value to an existing setting,
- e.g.
- a new language that is stored in
+ e.
+\begin_inset space \thinspace{}
+\end_inset
+
+g.
+\begin_inset space \space{}
+\end_inset
+
+a new language that is stored in
\begin_inset Flex Code
status collapsed
\end_layout
\begin_layout Enumerate
-Add an entry to both format lists (for conversion and reversion) in
+Add an entry to both format lists (for conversion and reversion) in
+\begin_inset Newline newline
+\end_inset
+
+
\begin_inset Flex Code
status collapsed
\begin_layout Plain Layout
-lib/lyx2lyx_lyx2lyx_2_1.py
+lib/lyx2lyx/lyx_2_2.py
\end_layout
\end_inset
.
- Add a conversion routine if needed (e.g.
- a new header setting always needs a conversion that adds the new setting,
+ Add a conversion routine if needed (e.
+\begin_inset space \thinspace{}
+\end_inset
+
+g.
+\begin_inset space \space{}
+\end_inset
+
+a new header setting always needs a conversion that adds the new setting,
a new document language does not need one).
Add a reversion routine if needed.
While the conversion routine is required to produce a document that is
recommendation were related to mixed version syntax, not ERT.
\end_layout
+\begin_layout Enumerate
+It would be nice if you could create a .lyx test file which contains instances
+ of all changed or added features.
+ This could then be used to test lyxl2yx and tex2lyx.
+ Unfortunately it has not yet been decided how to collect such examples,
+ so please ask on the development list if you want to create one.
+\end_layout
+
\begin_layout Section
Backporting new styles to the stable version
\end_layout
status collapsed
\begin_layout Plain Layout
-make check
+make alltests
\end_layout
\end_inset
\begin_layout Standard
In some cases a changed tex2lyx output is not a test failure, but wanted,
- e.g.
- if a tex2lyx bug was fixed, or a new feature was added.
+ e.
+\begin_inset space \thinspace{}
+\end_inset
+
+g.
+\begin_inset space \space{}
+\end_inset
+
+if a tex2lyx bug was fixed, or a new feature was added.
In these cases the stored references need to be updated.
- To do so, call
+ To do so if using autotools, call
\begin_inset Flex Code
status collapsed
\end_inset
- (autotools)
-\begin_inset Note Note
-status open
+ in the
+\begin_inset Flex Code
+status collapsed
\begin_layout Plain Layout
-FIXME: Add cmake command
+src/tex2lyx
\end_layout
\end_inset
- in the
+ subdirectory of the build directory.
+ If instead using CMake, call
\begin_inset Flex Code
status collapsed
\begin_layout Plain Layout
-src/tex2lyx
+make updatetex2lyxtests
\end_layout
\end_inset
- subfolder of the build directory.
- For convenience, this command does also produce re-exported roundtrip .lyx.tex
+ in the build directory or in the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+src/tex2lyx/test
+\end_layout
+
+\end_inset
+
+ subdirectory of the build directory
+\begin_inset Foot
+status collapsed
+
+\begin_layout Plain Layout
+Note that this is a case where a make target in the build directory can
+ affect the source directory, which might not be advisable.
+\end_layout
+
+\end_inset
+
+.
+ For convenience, these commands also produce re-exported roundtrip .lyx.tex
files.
Please examine the changed output carefully before committing the changed
files to the repository: Since the test machinery does not do a roundtrip
Once it is committed, it is quite difficult to verify whether it is correct.
\end_layout
+\begin_layout Standard
+Please
+\emph on
+do not
+\emph default
+ update the test references by opening them with LyX or directly running
+ lyx2lyx on them.
+ This would not work, since lyx2lyx and LyX produce slightly different files
+ regarding insignificant whitespace and line breaks.
+\end_layout
+
\begin_layout Subsection
Adding a new test
\end_layout
list and ask for committing if you do not have commit rights.
\end_layout
+\begin_layout Chapter
+Development policies
+\end_layout
+
+\begin_layout Standard
+This chapter lists some guidelines that should be followed.
+ This list is not complete, and many guidelines are in separate chapters,
+ such as
+\begin_inset Quotes eld
+\end_inset
+
+When is an update of the .lyx file format number needed?
+\begin_inset Quotes erd
+\end_inset
+
+ in Section
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:When-is-an"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+When to set a fixed milestone?
+\end_layout
+
+\begin_layout Standard
+Only set a fixed milestone (like 2.1.4 or 2.2.0) if at least one of the following
+ holds:
+\end_layout
+
+\begin_layout Enumerate
+Somebody is actively working on a fix.
+\end_layout
+
+\begin_layout Enumerate
+The bug is so severe that it would block the release if it is not fixed.
+\end_layout
+
+\begin_layout Standard
+If a bug is important, but nobody is working on it, and it is no showstopper,
+ use a milestone like 2.1.x or 2.2.x.
+ For all other bugs, do not set a milestone at all.
+\end_layout
+
+\begin_layout Section
+Can we add rc entries in stable branch?
+\end_layout
+
+\begin_layout Standard
+No.
+ We are supposed to increase the prefs2prefs version number with such things.
+\end_layout
+
+\begin_layout Chapter
+Documentation policies
+\end_layout
+
+\begin_layout Standard
+The main documentation consists of these files:
+\end_layout
+
+\begin_layout Description
+splash.lyx it is the first file you see after an installation.
+ We assume that a new user sees this.
+ It is therefore designed to be as simple as possible.
+ Therefore please don't add any new formatting, only fix typos etc.
+ Splash.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
+\end_layout
+
+\begin_layout Description
+Intro.lyx This is the manual new users will read to learn LyX.
+ It therefore uses a limited set of formatting.
+ For example a standard document class.
+ Since new users will first learn about the formatting possibilities of
+ LyX please keep this file that simple.
+ Intro.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
+\end_layout
+
+\begin_layout Description
+Tutorial.lyx our tutorial.
+ It must be always up to date.
+ Normally there is nothing to add since we don't want to overwhelm new users
+ with too much details.
+ The will learn these details while using LyX and we have special manuals.
+ Tutorial.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
+\end_layout
+
+\begin_layout Description
+UserGuide.lyx our main user guide.
+ It covers a mixture of basic and detailed information.
+ Some information is also in the Math and EmbeddedObjects manual so that
+ the UserGuide refers to these files.
+ UserGuide.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
+\end_layout
+
+\begin_layout Description
+EmbeddedObjects.lyx a special manual to explain things like tables floats
+ boxes etc.
+ in all detail.
+ EmbeddedObjects.lyx is up to date for LyX 2.1.x, currently maintained by Uwe
+ Stöhr.
+\end_layout
+
+\begin_layout Description
+Math.lyx a special manual to explain everything regarding math in all detail.
+ Math.lyx is up to date for LyX 2.1.x, currently maintained by Uwe Stöhr.
+\end_layout
+
+\begin_layout Description
+Additional.lyx this manual covers information that would be too much detail
+ for the UserGuide or would make the UserGuide uncompilable or only compilable
+ when installing a lot of special LaTeX-packages.
+ What should be in the UserGuide or better in Additional is a matter of
+ taste.
+ it is up to you to decide that.
+ Additional.lyx is not completely up to date for LyX 2.1.x.
+ Only chapter
+\begin_inset space ~
+\end_inset
+
+8 is up to date and currently maintained by Uwe Stöhr.
+ It certainly needs a rewrite and update.
+ For example many info in chapter
+\begin_inset space ~
+\end_inset
+
+2 and 3 are already covered by the UserGuide and/or the EmbeddedObjects
+ manual.
+\end_layout
+
+\begin_layout Description
+Customization.lyx this manual covers information how to customize LyX for
+ certain output formats, operating systems, languages etc.
+ It is currently completely out of date and needs a major rewrite and update.
+ If you do this please assure that your information are given for all OSes
+ and LaTeX distributions (meaning be as objective as possible).
+\end_layout
+
+\begin_layout Standard
+There are only 4
+\begin_inset space ~
+\end_inset
+
+rules in editing the docs:
+\end_layout
+
+\begin_layout Enumerate
+If you are not the maintainer of a doc file or a chapter/section, you MUST
+ use change tracking so that the maintainer could review your changes
+\end_layout
+
+\begin_layout Enumerate
+Respect the formatting of the document.
+ The different files use different formatting styles.
+ That is OK and has historic reasons nobody fully know ;-).
+ But it is important to be consistent within one file.
+\end_layout
+
+\begin_layout Enumerate
+All changes you make to a file in one language MUST also go the file in
+ the other actively maintained languages.
+ Normally the maintainer does this for you, if you are the maintainer, you
+ must do this by copying or changing the changed or added text to the other
+ files so that the translators sees the blue underlined text and know what
+ they have to translate and what was changed.
+\end_layout
+
+\begin_layout Enumerate
+You MUST assure that the document is compilable as
+\begin_inset Quotes eld
+\end_inset
+
+PDF (pdflatex)
+\begin_inset Quotes erd
+\end_inset
+
+ after your changes.
+\end_layout
+
\end_body
\end_document
projects / lyx.git / blobdiff