Moving to Beta & Git Hooks #24
Replies: 2 comments 7 replies
-
That's cool.
Good idea. In the last part of the sentence, I think you meant to write "so it only needs refreshing to see changed text".
I think
I don't think that's true anymore. According to the GitHub documentation, the branch and directory can be selected:
Only
Is good. Here you can maybe use Travis again to automate the HTML update.
I agree. What do you think about letting
Works here, just takes a while: $ git branch --show-current
alpha-dev_rake
$ ./validate.sh
================================================
Validating Code Styles via EditorConfig Settings
================================================
Using:
* Node.js v16.8.0
* EClint v2.8.1.
/// Test Passed /// |
Beta Was this translation helpful? Give feedback.
-
No I meant images, because the published HTML doc uses Data URIs, i.e. images are embedded in the document via URLs and Base 64 encoding, so the doc can be downloaded as a single standalone file, images and all. But when developing the doc, you need to be able to see changed images without having to re-convert the document to HTML, hence the need to invoke Asciidoctor without the Data URIs option for the HTML Preview doc.
Yes, I like that more too, there's no reason why we shouldn't translate the title. My only concern is that the (well known) Pro Git book is often referred to a "The Git Book" for brevity: https://git-scm.com/book/en/v2 so I was wondering if this could lead to confusion, or to problems finding it via search engines — googling "git book" definitely results in Pro Git showing up first. Probably there weren't many books on Git in German at that time, so a simple title like "Git Buch" could only refer to that book. In English though there are many books on Git, so a generic title like this might not play out very well unfortunately (whereas keeping part of the title in German does the trick). Also, I didn't personally mind keeping the German title, which in any case one can intuitively guess that "buch" means "book", but then if we do so we'll have to add "English" or "EN" to avoid confusion with the German original. But these consideration are mostly about the book title, not the filename (which doesn't have to match the title 100%).
Right. They keep changing these settings all the time, it's hard to catch up. I'll need to actually test it though, because the screenshot in that page are hard to read so I couldn't check all the options. So, assuming we can serve GHPages from the The benefits of serving from I don't have any problems having Beta versions in
I'm not quite sure either should be default really. Bear in mind that once we start adding syntax highlighting to the book, build times will increase significantly (unless the preview is built without syntax highlighting), so it might be a feature worth making available only when one really needs to rebuild the document. Of course, it really depends on what other tasks will end up in the Rake file, which is what will ultimately decide what the default should do (usually Default includes more than one task); so right now it's mostly brainstorming.
Sometimes (and very often when working on docinfo files and CSS) I need to inspect the generated HTML file, either manually in the editor or via some dedicated tools, so it's more practical to have it in the same folder as the sources and ignore it. Also, bear in mind that the generated HTML preview file is actually a Rake target (which is why if it's deleted or absent it gets created by Rake) so I think it has to be within the repository, since Rake is designed to track files within the directory tree where the
Yes, seems to work again also on my machine, after the reboot, but it takes ages. The new script that doesn't work well with big repositories. Also, I think the problem are the SVG files, because EClint is known to have problem handling XML files (fails parsing them properly, lots of false positives). Even though there are no rules for SVG files, it's not excluding them entirely. E.g. I noticed that if I run the Dia downloader script, then EClint stops working. Even though the Dia bins folder is ignored by Git, I tried to prevent EClint from scanning it, but since it has no folder or file exclusion rules, all I could try was to set a match all pattern for that folder with all rules |
Beta Was this translation helpful? Give feedback.
-
But the sentence was about the preview HTML, so I was wondering why it "needs refreshing to see changed images" if it doesn't use Data URIs. Anyway, thanks for the further explanation. I already thought that you meant it that way. Good idea.
I like it. What else occurred to me: The German Git Book (english)
But that requires that we continue to commit the HTML doc every time we make a change, as before. But your new idea is to stop doing that (only commit the changed AsciiDoc sources). Maybe we can use that, then we don't need HTML files for the GH Pages anymore: jekyll-asciidoc Or what do you think about using a separate orphaned branch just for the HTML doc in the beta stage? GH Pages will then generate the pages from there. Here everything in detail: $ git checkout --orphan=html-doc
$ git reset --hard
$ git commit --allow-empty -m "Initial"The branch With every commit we create or merge in $ git checkout beta-dev
$ rake publish
$ git checkout html-doc
$ git add docs/git-book.html
$ git commit --amend --no-edit
$ git checkout beta-dev
$ rm docs/git-book.htmlWhen we finish the beta stage and release the final version, we can create a commit in the
Ok, I didn't know that this is possible. Sure, then maybe it makes more sense that default (just
I saw that you use You could additionally specify the parameter This way you would have the exclusion functionality you are missing with EClint and can exclude more files that are not in |
Beta Was this translation helpful? Give feedback.
-
Unfortunately we can't use the AsciiDoc extension for Jekyll on GHPages; I don't remember if it's because it's blocked, or because you can't use custom extensions. Either way, when I last checked it wasn't usable.
Well, initially GHPage used to be only available from the orphan branch Also, storing the HTML file in In our project, we had to use orphan branches for various reasons, one being the considerable size of all the documents (PDF, HTML, and Zips with code), so having them on an orphan branch avoids cluttering the repository, and we now and then squash together all the commits in the orphan branch, to regain disk space. But in general, I dislike it and avoid it if I can.
Yes, we have total freedom in deciding what the default tasks will be, etc. Rake follows the Make conventions here — Whether we'll add code styles validation to certain tasks will be up to us, and we can definitely make any task branch-aware, since we can invoke Git from the Rakefile, etc.
The problem is that EClint does! There are no ignore pattern that can be passed to EClint, so it will scan any subfolders (except
I'll get back to this point later one (right now, fever levels prevent me from following tech details). But yes, I'm aware there's a problem and that it needs to be fixed, both with the Git options being used, but mostly because EClint fails to handle to paths with escape chars returned by Git — if a file contains an accented letter like I'll have to postpone any code operations that require using more than 2 neurons to when the tooth extraction is over, and fever levels down to acceptable. Right now is a series of up and downs, all day long. |
Beta Was this translation helpful? Give feedback.
-
Yes, I know. They have their own commits history, which has besides advantages also disadvantages. If you want to merge commits from orphaned branches into the normal commit history (e.g. into the
I was thinking too complicated. The simplest solution is if we create an ignore rule in
If GH Pages also respects
Wish you a speedy recovery. |
Beta Was this translation helpful? Give feedback.
-
Beta vs Final@SicroAtGit, I think that for the Beta release we should make things simple, and just serve the GHPages website from the I just wanted to make the Beta book visible so we can get contributors to participate to the polishing stage. We'll probably need a Git hook to ensure that any commit, merge or rebase to Book TitleThe only thing that I'm still unsure about is the title translation. I keep liking the German style title "The Git Buch", but we might have to consider that such a title could make the book harder to find via search engines. The problem with "Git Book" is that when you search for the term the book Pro Git shows up. E.g. in DuckDuckGo you get in first position:
which is why Pro Git is also known as the "Git Book". Search engines aside, I feel that keeping the German "Buch" in the title confers a strong identity to the book, but that's just my opinion. Alternatively, we'll have to make an editorial choice and come up with some other title (which I don't really like much, since it's a translation, but it's not something unusual either). In any case, this shouldn't be a reason to block the ongoing work, since the HTML files in the website will have to be called just I'll try to fix the remaining pending tasks from #22, and switch to Beta stage as soon as we're ready to go, so the book can finally be visible via the website and I can ask for support on the GH Community. |
Beta Was this translation helpful? Give feedback.
-
Done!The simplified setup version for the Beta stage was merged to the alpha-dev branch. We can keep using this discussion for deciding how the final book will be handled in the future (orphan branches, etc.). |
Beta Was this translation helpful? Give feedback.
-
|
Good work!
Good idea.
Yes, I also need to think about it some more. The Git Buch is good. I just wonder if non-German speakers understand by Buch that it's a book. Maybe it would help if we add a description metatag in the HTML and describe there that it is a book. The search engines show the text that is in the description metatag in the search results.
When I search with Startpage for The Git Buch, the result looks like this:
However, on which position a web page appears in the search results also has to do with
If I search for "The Git Buch" (in quotes) no search hit is displayed. This looks good :-) |
Beta Was this translation helpful? Give feedback.
-
|
For the time being, I've opted to name the file along the "Git Book" lines, as well as the Git.io posh URL, since these two would help correct search engines indexing. As for "The Git Buch", the repository name being I've also been thinking that in reality the title of the German book is just "Git" followed by the subtitle — i.e. Git, Verteilte Versionskontrolle für Code und Dokumente (Git, Distributed version control for code and documents) — so probably "Git Buch" is a kind of alias, mostly associated to the original website domain, but in the original catalogue of the publisher the book was indeed referred to as "Git". So we'll probably have to pick a formal title, on the one hand, and push for a short alias too ("The Git Buch"), the latter depending more on how we refer to the book in the README, links, whenever we promote it, and in our "Preface to The English Translation" (which we'll have to add to the book), etc. The original title is definitely too short, and we'll have to come up with an alternative translation since books are catalogued mainly by the title, the subtitle being often shown only in the actual book page (I'm thinking of proper book metadata here, not search engines). We also still have in the repo the original README in German and its translation in English ( Since this topic still needs further thoughts, I've started a dedicated Discussion in #28, with a resume of the various points that came up so far. |
Beta Was this translation helpful? Give feedback.
-
@SicroAtGit, we need to decide what to do with the Git hook scripts, since we're heading for the first Beta release (see #22).
install-git-hooks.shuninstall-git-hooks.shI've starting working on the Rakefile in the
alpha-dev_rakebranch.Right now, the precommit hook CDs
docs_srcand executes./build.sh— but thedocs_src/build.shscript has now been deleted and replaced by therake previewtask, which does the same exact thing (but invoking the Asciidoctor API instead of the command line tool).Unlike shell scripts, Rake can be invoked from any repository subfolder and will do the same job — i.e. Rake always runs from the folder where the
Rakefileis stored.I'm planning to make the preview document
docs_src/Git-Buch_EN.htmlignored by Git, it's only goal being for developers to peek at changes with an HTML doc that doesn't use Data URIs, so it only needs refreshing to see changed images.Since we'll be publishing the HTML book on GHPages, will be building the HTML book in the
docs/folder (still haven't decided the actual filename, could beGit-Buch_EN.html,GitBook.htmlorGit-Book.html, we'll discuss that). Also, this requires us to merge the book intomaster, since GHPages served fromdocs/only works on the default branch.In any case, updating the HTML document in the
docs/folder will be considered "publishing" the book, and will probably be assigned totake publish(haven't yet decided what the default task will be).Contributors will be submitting PRs and changes to
beta-devbranch, and the HTML book will need to be updated (published) only when merging tomaster.IMO it would be better if contributors don't rebuild the HTML book, because it would lead to conflicts if they have to rebase, and because any differences in the Asciidoctor version employed would result in different HTML tags and CSS.
Instead, we'll be rebuilding the HTML docs before merging from
beta-devintomasteronly — which makes sense, since the doc will only be visible online once it's onmasterbranch, and for previews there's the Preview Doc (untracked).I'm not quite sure that we should keep a Git hook that forces rebuilding the document then. I was thinking instead of having a hook that validates the code styles via EClint, but today I discovered that EClint is not working anymore on this repository (could be that the machine needs a reboot, or due to the Dia downloaded binaries which clutter the repository, although ignored).
I'll have to check if the EClint alternative tool is productions ready (last time I've checked, it still lacked some features we need, but some time has past now). Also, the new edited validation script, which only runs EClint of files which are tracked by Git, takes too long (almost five times longer) and is also buggy in various cases (deleted files, etc.). I should look into a better solution via Rake and a custom Ruby method that could filter out EClint error logs, instead of invoking Git so many times.
So, roughly the issues described above are the starting point for the switch to Rake for automating the project, and the changes required to publish the book on GHPages, which we should decide upon and sort out before moving into the Beta stage.
Even though, this Issue was supposed to be just about the Git hook scripts, it inevitably had to spread out to the general changes that are awaiting us, after all these hooks are there to serve the project even if/when it changes.
All suggestions are welcome, for most of it still mostly brainstorming.
Beta Was this translation helpful? Give feedback.
All reactions