| 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. |