Skip to content

Replace dockers/MathJaxFonts with KaTeX/katex-fonts submodule#891

Merged
k4b7 merged 2 commits intomasterfrom
font_submodule
Nov 28, 2017
Merged

Replace dockers/MathJaxFonts with KaTeX/katex-fonts submodule#891
k4b7 merged 2 commits intomasterfrom
font_submodule

Conversation

@k4b7
Copy link
Member

@k4b7 k4b7 commented Sep 17, 2017

Fixes #816.

I ran make build to verify that the build script grabs the fonts from the new submodule. The release script should remain unchanged because it has everything it needs in the build folder.

@k4b7
Copy link
Member Author

k4b7 commented Sep 17, 2017

After replacing static/fonts with a symlink I loaded 0.0.0.0:7936 to verify that the test program still works.

@ry-randall
Copy link
Member

ry-randall commented Oct 18, 2017

The code changes look fine to me. I'm not too familiar with submodules, but it seems like they add some extra overhead.

In particular (gathered from https://medium.com/@porteneuve/mastering-git-submodules-34c65e940407):

  1. Every time you add a submodule, change its remote’s URL, or change the referenced commit for it, you demand a manual update by every collaborator.
  2. Forgetting this explicit update can result in silent regressions of the submodule’s referenced commit.
  3. Commands such as status and diff display precious little info about submodules by default.
  4. Because lifecycles are separate, updating a submodule inside its container project requires two commits and two pushes.
  5. Submodule heads are generally detached, so any local update requires various preparatory actions to avoid creating a lost commit.
  6. Removing a submodule requires several commands and tweaks, some of which are manual and unassisted.

Should the readme be updated to help contributers understand how to work with the new submodule for fonts?

@k4b7
Copy link
Member Author

k4b7 commented Oct 18, 2017

I have a few git aliases set to help with managing submodules:

  # Versions of commands that handle submodules properly.
  co = "!f() { git checkout \"$@\" && git submodule update --init --recursive; }; f"
  p = "!f() { git pull \"$@\" && git submodule update --init --recursive; }; f"
  m = "!f() { git merge \"$@\" && git submodule update --init --recursive; }; f"
  gsu = "!f() { git submodule sync --recursive && git submodule update --init --recursive; }; f"

I agree that it definitely adds additional overhead. Another option would be to turn the new font repo into a npm module.

@edemaine
Copy link
Member

Hmm, an npm module is an interesting idea. The copying of fonts to dist is part of npm install anyway, so we can rely on modules being installed...

@ry-randall
Copy link
Member

I agree it's an interesting idea. Would there be any concerns with turning that code into an npm module?

@k4b7
Copy link
Member Author

k4b7 commented Oct 20, 2017

Although I made the suggestion, I have a couple concerns about using npm modules:

  • it can be harder to test changes the require changes to code across modules. In this case I don't think that would really be an issue because you can inspect the font files and see if the glyphs are there (or not)
  • probably fewer people will be willing/able to publish the npm module. This could be worked around by pointing to the git repo directly and specifying a particular sha.

@edemaine
Copy link
Member

FWIW, npm link offers one way to test changes between the two repos, without having to npm publish. Probably not quite as convenient as submodules though, where you have everything right there in the same tree. Submodules are also closer to our current approach.

I do feel like it's good to optimize for people who don't care about (developing) the fonts, and there is a slight advantage there. On the other hand, it doesn't take much training to learn git submodules --update (if that's the right command).

@edemaine
Copy link
Member

edemaine commented Oct 21, 2017

Back to the PR, did you test npm start? (I don't know off hand whether this triggers build.)
Do the release scripts need to change at all?

@k4b7
Copy link
Member Author

k4b7 commented Oct 23, 2017

@edemaine the release script runs make dist which run make build which copies over the font files to the build/fonts same as before so release.sh should just work.

@k4b7
Copy link
Member Author

k4b7 commented Oct 23, 2017

I'll double check npm start tonight and see if the test page works.

@ry-randall
Copy link
Member

ry-randall commented Oct 30, 2017

After having thought of it a little more, I think using a submodule should serve just fine. I'm finding it hard to think how you'd use semver for a font repo. It just feels a little odd.

The code here looks fine, have you had a chance to test via npm start?

@k4b7
Copy link
Member Author

k4b7 commented Oct 30, 2017

have you had a chance to test via npm start?

😭 just been really busy with other stuff lately. Running npm start shouldn't take that long though, going to try to get to it this evening.

@k4b7
Copy link
Member Author

k4b7 commented Nov 24, 2017

@rrandallcainc I ran npm start and then loaded http://0.0.0.0:7936 and saw:
screen shot 2017-11-24 at 4 57 28 pm

@k4b7
Copy link
Member Author

k4b7 commented Nov 26, 2017

I'm going to take @rrandallcainc's suggestion of updating CONTRIBUTING.md to provide some tips on how to deal with submodules.

@k4b7
Copy link
Member Author

k4b7 commented Nov 28, 2017

@rrandallcainc I've added a section to CONTRIBUTING.md title "Working with submodules".

Copy link
Member

@ry-randall ry-randall left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me 👍. Thanks for updating contributing.md

@k4b7 k4b7 merged commit 9e6eb3a into master Nov 28, 2017
@k4b7 k4b7 deleted the font_submodule branch November 28, 2017 12:25
This was referenced Nov 28, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants