Debian Codegraph @

texmf-dist/doc/latex/koma-script/CONTRIBUTING.md

raw
1 # Contribute to KOMA-Script
2
3 Open source projects are highly dependent on user participation. This is
4 especially true for projects such as KOMA-Script, which consist of tens of
5 thousands of lines of code and hundreds of pages of documentation in two
6 languages. In the past, there have been repeated phases with individual
7 instances of assistance. The first manual was created in the 1990s thanks to
8 the commitment of one user. Similarly, the original letter class was
9 contributed by another developer. Individual users have also repeatedly
10 distinguished themselves in testing and translation.
11
12 In fact, however, KOMA-Script has been and continues to be kept alive and
13 developed mainly by a single developer. Since the development of the LaTeX
14 kernel and core packages is progressing at a rapid pace, this is hardly
15 feasible anymore. Therefore, assistance is urgently needed.
16
17 # The Currently Active Contributors
18
19 * Markus Kohm — Maintainance, Development, Implementation, Support and Handyman
20 * Marei Peischl — Tagging
21
22 As can be seen, the testing area is completely vacant and all other areas are
23 underrepresented. So **your help is needed!**
24
25 ## Testing
26
27 There are two types of test:
28
29 1. Testing with current releases
30 2. Testing code from ongoing development
31
32 Anyone can perform the first type of testing. All you need to do is regularly
33 update the LaTeX distribution you are using and then check your existing
34 documents and, if necessary, any test documents you have developed yourself to
35 ensure that they still function properly. If an error occurs, it should be
36 narrowed down using a binary search and then reported via [the issue
37 tracker](https://sourceforge.net/p/koma-script/tickets/),
38 together with the resulting minimal working example. Please *don't forget to
39 minimize the document preamble.*
40
41 Anyone can get involved in the transition to the second type of testing. In
42 addition to the official release, there is always a pre-release version of the
43 LaTeX kernel and some core packages that is already at an advanced stage of
44 development. To test these, LaTeX runs are performed with `pdflatex-dev`,
45 `lualatex-dev`, or `xelatex-dev` (for which the same applies as for `xelatex`)
46 instead of with `pdflatex`, `lualatex`, or (the now no longer recommended)
47 `xelatex`. For more details, see
48 [`latex-base-dev`](https://www.ctan.org/pkg/latex-base-dev). In addition to
49 testing existing documents, it is also desirable to test the changes
50 documented in the current LaTeX News (the latest issue of `ltnews*.pdf`,
51 currently only available in `latex-base-dev`). A particular difficulty here is
52 assessing whether problems are general problems of the future LaTeX version or
53 specifically related to KOMA-Script. This can be tested in part by trying to
54 replace the KOMA-Script classes with standard classes in the complete minimal
55 examples and removing KOMA-Script packages. If the problem persists, it should
56 be reported to the LaTeX team. Otherwise, and in unclear cases, reports can be
57 made either to the LaTeX team and [the KOMA-Script issue
58 tracker](https://sourceforge.net/p/koma-script/tickets/), or only to the
59 latter.
60
61 The second type of test requires a little more preparation. To do this, you
62 need to download the [code for the current KOMA-Script
63 development](https://sourceforge.net/p/koma-script/code/HEAD/tree/trunk/). This
64 can be done either by using the “Download Snapshot” option provided there or
65 by checking out the current source into a working directory using a Subversion
66 client (e.g., `svn` on Linux or OSX, or TortoiseSVN or SilksSVN on
67 Windows). You can then install this developer version without the manual using
68 `l3build install` or with the manual using `l3build install --full`. You can
69 undo the installation with `l3build uninstall`, so that the KOMA-Script
70 version from the TeX distribution is used again. You can also specify a
71 different target tree for the installation with
72 `l3build install --texmfhome <TEXMF-ROOT>`.
73 `<TEXMF-ROOT>` must be set to the root directory of the target
74 tree. For MiKTeX users, this specification is even mandatory. Depending on the
75 TeX distribution, this root must then be integrated as an additional TEXMF
76 tree and removed again after the tests have been completed. For more
77 information on activating and deactivating additional TEXMF trees, refer to
78 the instructions for the TeX distribution used. With the developer version
79 installed, you can then also perform tests as described above.
80
81 ## Support
82
83 As an experienced user, you can also provide assistance to the support
84 team. To do so, log in to SourceForge, subscribe to the issue tracker, and
85 follow the reports that come in there. You can now provide assistance in
86 various ways:
87
88 * If a reported issue seems familiar to you, i.e., you believe it has been
89 reported before, you can comment on the new report to provide a link to the
90 already known issue. This is quite easy to do by entering the number of the
91 report in square brackets and adding a hash sign, for example `[#12]` for a
92 link to Issue [#12](https://sourceforge.net/p/koma-script/tickets/12/). If a
93 solution to a reported problem can be found in the
94 [Wiki](https://sourceforge.net/p/koma-script/_list/wiki), you can also link
95 to it. It is usually desirable to link to both the corresponding entry in
96 the German and English Wiki. This can be done by using, e.g.,
97 `[wiki-en:HowTo]` (English) and `[wiki-de:HowTo]` (German). The part after
98 the colon has been deliberately chosen to be identical in both languages.
99
100 * If a problem description seems unclear to you and, e.g., a complete
101 minimal example or information about the KOMA-Script version used is
102 missing, you are welcome to point this out *politely* and, if necessary,
103 offer assistance in supplementing the missing information.
104
105 * If you know a solution to the problem described—regardless of whether it has
106 to do with KOMA-Script or not—you are welcome to provide the solution.
107
108 * If you recognize that a problem is unrelated to KOMA-Script, you may also
109 point this out and, if necessary, provide assistance on where the problem
110 should be reported or inquired about.
111
112 It should be noted at this point that many support requests are still received
113 by email. As a rule, the KOMA-Script author asks that problems which appear to
114 be of general interest be reported in the issue tracker. Unfortunately, this
115 is often not done. Sometimes the KOMA-Script author adds them
116 himself. However, such reports often need to be processed, for example
117 translated into English. If you have enough experience to feel confident about
118 doing such processing and translation, please feel free to contact us.
119
120 ## Wiki
121
122 [The KOMA-Script Wiki](https://sourceforge.net/p/koma-script/_list/wiki)
123 already contains a large number of helpful articles,
124 especially in the HowTo section. Most of them are edited articles from the
125 former KOMA-Script Documentation Project, also known as the old KOMA-Script
126 homepage. Some are completely new. However, there are never enough such
127 pages. So if you discover an interesting problem for which KOMA-Script offers
128 a nice solution, add it there. However, we ask that you write all articles in
129 both German and English and sort them into both wikis. All articles in the
130 wiki are considered public domain! Please do not publish any articles there
131 under special rights restrictions, as this always hinders the further
132 development of articles and runs counter to the purpose of a wiki for an open
133 source project.
134
135 ## Development
136
137 The actual development of KOMA-Script, i.e., improving the code and
138 implementing new features, is also possible. Improving the code is based on
139 testing and support (see above) and supplements this with proposed solutions
140 through code changes. This can be done in a variety of ways, for example,
141 through push requests, proposed solutions in the issue tracker, or direct
142 collaboration. For the latter, please contact the KOMA-Script maintainer by
143 email. However, please understand that not every developer can become a
144 write-access user in the repository.
145
146 Packages are also frequently split off from KOMA-Script. In many cases, this
147 is done in the hope that a new maintainer for the package in question will be
148 found sooner or later. If you are interested, please contact the KOMA-Script
149 maintainer by email.
150
151 Even within KOMA-Script, there are individual packages that have not (yet)
152 been split off but are nevertheless relatively independent from the rest of
153 KOMA-Script. Here, too, an internal, gradual takeover of development, leading
154 to a split-off as a separate project, is conceivable.
155
156 And then there are special areas that may have their own manager who drives
157 and monitors development in close cooperation with the main maintainer. One
158 example is the area of tagging and metadata, which currently has its own
159 manager (see above). Other such areas are possible.
160
161 ## Maintainance
162
163 Last but not least, the entire development of KOMA-Script should be
164 transferred to a new maintainer at some point. The target date for this is
165 currently April 2032.