Closed ddanielr closed 1 year ago
I wouldn't discount the use of a containerized environment for doing website changes as I've had conversations with at least two accumulo devs who plan on using it besides myself.
Overall I've found that build environments that can be quickly rebuilt and shared helps reduce "works on my machine" issues and update rot.
I chose a source container that matches the current ruby version with the hope that there were minimal changes between the containerized environment and any bare metal development environments.
The gem lock updates were mostly generated from the containerized version, however I'm happy to spend more time seeing if I can eliminate those differences.
I explicitly did not add the htmlproofer to the GitHub build step as it currently finds thousands of html linking errors in the current site.
A large majority of these findings are valid and I did not want to add a failing build step that would block other documentation work.
Instead, adding it as a manual run option to allow for partial fixes seemed the best approach.
However, I can split the validate work into a secondary container that uses a separate gem file and should reduce the possibility of conflicts with a local dev environment.
I wouldn't discount the use of a containerized environment for doing website changes as I've had conversations with at least two accumulo devs who plan on using it besides myself.
I'm not discounting it. I'm fine with it. I'm just saying I'm uncertain about how much use it will get, given that none of the people who have been doing the work on the website have had a problem updating the website in its absence.
Overall I've found that build environments that can be quickly rebuilt and shared helps reduce "works on my machine" issues and update rot.
I agree, but I don't find Docker any quicker than GitHub Actions builds or local Jekyll bundler builds without Docker. But, it doesn't matter, because I am fine with adding the Dockerfile, even if it gets no use at all.
The gem lock updates were mostly generated from the containerized version, however I'm happy to spend more time seeing if I can eliminate those differences.
I think the issues I saw were related to the fact that I have a much newer version of GCC than the native extensions of those gems were developed with. Normally, I'd be fine with updating Jekyll, and then updating any dependent gems. But, if those gems' native extensions can't be built with the latest GCC, then that's going to cause bugs temporarily until those issues are fixed. This is just a timing issue... we're currently trying to make some updates to the site, and those breaking changes are coming at a bad time. There is nothing wrong with the previous gem versions, so far as I know. They might have some vulnerabilities or bugs or features that we're not encountering, but that's not causing a problem in our isolated build environments with known input, so until we can figure that out, I think the gems should just stay locked where they are.
I explicitly did not add the htmlproofer to the GitHub build step as it currently finds thousands of html linking errors in the current site.
A large majority of these findings are valid and I did not want to add a failing build step that would block other documentation work.
That's why I think it should serve as its own PR, after those links are fixed, or in conjunction with those fixes, rather than included as part of a completely unrelated Dockerfile PR.
For what it's worth, I have previously used a Python-based Link Checker to manually check stuff using a local bundle exec jekyll serve
. That might be easier to configure in GitHub Actions... I'm not sure. I just know the crawler/checker itself does not necessarily need to be ruby-based just because the static site is built with ruby. I don't have a preference.
The main thing regarding the link checking is that it's just wholly unrelated to the Docker stuff, and can easily be its own change, along with the actual fixes to the broken links. It's a good QA thing to add... it's just not related or dependent on the local build using Docker. It would be related, however, to the fixes of any broken links.
If I were to make a large change to the website where I needed local preview, I would use this new docker container.
I would use the Docker container to test changes to the website locally. Like I said, I have had issues getting everything that is currently required installed. Using a Docker image that provides a working environment for everyone, without everyone having to go to the trouble of finding and installing all of the dependencies, sounds great.
@ctubbsii I worked on this a bit more and I was able to add a docker environment without modifying the original Gemfile or Gemfile.lock.
This PR adds two containers, one is the containerized build environment. The other is a validation container that can be run against any directory that contains rendered html.
This should allow your local development environment to remain unchanged while still providing a containerized solution.
Are there any more requested changes to this code? Or can this be merged?
Adds a dockerfile for building a containerized development environment. Also adds the htmlproofer gem for use of validating html structure and links.