Developer onboarding - Githubissues

v6ak commented 1 year ago

For developer onboarding, there is development.md. I find it helpful, but not perfect. There are several things that can be improved.

Link to development.md from README.md

If it was linked from README.md, it would save me some time. I wouldn't try docker-compose, which seems to be useful for production deployment rather than for development.

Prerequisites

JDK (not sure about versions that are OK; I've used JDK 17)
SBT (latest version of sbt-launcher is OK, because it will download the required version)
Elm compiler (I've used the latest version)
Tests: tesseract unoconv wkhtmltopdf tesseract-langpack-deu

Joex mentions

A link to https://docspell.org/docs/joex/intro/ would be useful.

BTW, the documentation doesn't show well on computer with a narrow window like window.document.body.clientWidth == 701. In Firefox@Fedora, it shows just the menu, without an ability to scroll it. When I make the window absurdly large (almost 3000px height, which is far larger than my screen), I can see the content under the menu. But maybe I should open a separate issue for this.

Developing Frontend

Starting restserver/joex

This section suggests to call sbt "restserver/reStart". It doesn't work, because it launches the server in background and returns control back to SBT, which quits. I need to run sbt and then restserver/reStart.

Modified frontend sometimes isn't reflected in browser

When I modify the frontend, the changes are reflected only when I use Ctrl+F5 (in Firefox). When I reload with F5, I get the old version, probably because the data is received from service worker (as shown in developer console). This happens even though I use DOCSPELL_ENV=dev.

eikek commented 1 year ago

Thank you for reading and trying! Of course, feel free to improve the documentation (including readme and development.md) any time! Always good to make changes with a fresh mind.

JDK: version is not really important. Anything 11+ is ok. The CI runs with JDK11 SBT: also not very important, just not too old Elm: version in use is 0.19 - which is currently the newest

I agree on all the points. I never had problems with the documentation not letting me scroll, but that would be good to fix, of course.

eikek commented 1 year ago

Update for the jDK version: since recently (#2354) it is now JDK17 or newer. A good place to find this are the workflows in the .github folder.

v6ak commented 1 year ago

I'd like to adjust some parts, just not my top priority.

Few notes on that:

It seems that the development.md is (indirectly) linked from the root README.md, just not in the way I was looking for. (It is under Contributions/Support, I was looking for “devel".) Maybe a slight change in wording will be helpful.
Software versions aren't my primary issue, and maybe link to .github directory will be enough (so that the documentation wouldn't get outdated easily).
Not sure what to do with frontend modification. Is requiring force reload (Ctrl+F5 or so) enough? Is there an easier way?

v6ak commented 11 months ago

One more issue: Tailwind CSS regeneration is unclear. I would expect watch-css to do the job. It seems that every time I use a previously-unused Tailwindcss class, I have to:

run reStart (at least for restserver; joex is probably irelevant there)
reload page
log-in again
force reload (Ctrl+F5 in Firefox) – it isn't enough to do this in step 2.

While I could run ~reStart, it doesn't look like a good fit for adjusting the UI, as it takes much more time even when no frontend reload is needed.

eikek commented 11 months ago

The script in project/ should be enough to update css. Login shouldn't be required if you use the remember-me feature. Reloading the page is necessary, though. Running reStart is really overkill and too slow :). I always use the bash script; not sure why it doesn't do in your case.

eikek / docspell