Document config.preprocessor_priority

[johnjbarton]

No description provided.

[devoto13]

This change is included in 5.0 docs, but it was also available in Karma 4.3 and 4.4.

I'm thinking whether we should add 4.1, 4.2, 4.3 and 4.4 documentation versions or is it better to treat 4.0 as 4.x and update 4.0 with docs changes from all minor versions. Probably mentioning somewhere in which minor the specific API was added.

Former approach is a bit simpler, but my concern is that version dropdown will grow too fast.

@johnjbarton What do you think?

[johnjbarton]

I added the v4.3 info to this PR. I think that plus the 4.x approach is a good compromise.

[devoto13]

The problem is that all .html files are re-generated from the .md sources on documentation build, so this change will be lost next time we update docs.

What you need to do is something like:

# Pull .md files from Karma v4.4.1 release into `src/content/4.0` folder and re-generate documentation.
$ ./sync-docs.sh v4.4.1 4.0

Then add relevant since text to the src/content/4.0/config/preprocessors.md and run ./node_modules/.bin/grunt build to generate .html with these ad-hoc changes.

[johnjbarton]

And we need to do that for every .x feature documented?

[devoto13]

Going forward, yes.
I'm okay with not doing this for 4.x changes if it is too much effort.

[johnjbarton]

So if we go with 4.x.y documentation is the documentation update workflow easier? (In my experience the complexity of the current doc soln is an inhibitor for updates).

[devoto13]

The alternative is to add 4.1, 4.2, 4.3, 4.4 and all future minors to the version dropdown and generate a complete documentation for each minor version.

Then workflow is easier:

$ ./sync-docs.sh v4.1.0 4.1
$ ./sync-docs.sh v4.2.0 4.2
$ ./sync-docs.sh v4.3.0 4.3
$ ./sync-docs.sh v4.4.1 4.4

But we probably gonna make a version dropdown too big pretty fast.

I was thinking to do docs updates automatically by adding a plugin to semantic-release in Karma repo if we can manage to give karmarunnerbot push access to this repository.

[devoto13]

On the other hand we can update templates to make the dropdown more compact by putting minor on the same line.

Something like:

5.0
4.0 4.1 4.2 4.3 4.4
3.0
2.0
etc

I would say let's go with separate documentation for each minor version as it is easier to maintain. I'll submit a PR to make the version dropdown more compact in the coming days.

[johnjbarton]

give karmarunnerbot push access to this repository.

I think I did that now.

[johnjbarton]

So... now this PR needs be merged and the sync-docs run?

[devoto13]

As I said before, changes to HTML files will be overridden on the next documentation update, so no point merging current diff. All content changes should be done in the source Markdown files.

The current change is different from what is currently in https://github.com/karma-runner/karma/blob/master/docs/config/04-preprocessors.md. So I would say the way to go is to submit changes from this PR to documentation sources in the karma repository and submit a separate PR with commands from #55 (comment).

Once above are merged you can optionally copy paste the Markdown changes from docs/config/04-preprocessors.md in karma repository to src/content/4.3/config/04-preprocessors.md and src/content/4.4/config/04-preprocessors.md, run ./node_modules/.bin/grunt build and submit it as a PR to include this change in the documentation for older versions. (This is a one time complication as we're doing an ad-hoc update of the older version.)

[devoto13]

Moved to karma-runner/karma#3673