Til Tracker

PDF tab title incorrect (comes from embedded metadata)

Issue: When I opened linked PDFs (cv.pdf, cover_letter.pdf), the browser tab showed an incorrect title (e.g., "Minimalist White and Grey Professional Resume").
Cause: The browser tab title for directly viewed PDFs is taken from the Title property embedded in the PDF's metadata, set when the PDF was created.
Resolution: I edited the PDF metadata using a dedicated PDF editor (Nitro PDF Pro, as Preview was insufficient) to change the Title property within each PDF file. I re-copied the modified PDFs to public/documents/.
Learning: The display title for linked assets like PDFs is controlled by the asset's internal metadata, not the HTML page linking to it. I learned editing requires tools capable of modifying PDF properties (Preview might not work; Acrobat, Nitro Pro, or other editors are needed).

Tags: frontend workflow debugging

Learned on: April 22, 2024 Edit

`rails db:seed` failed (NameError due to heredoc interpolation)

Context: I ran the generated seed script which populated Learning records from LEARNINGS.md. The error occurred processing an entry whose body contained the literal text params[:tag]. The default heredoc syntax (<<~BODY) attempted Ruby interpolation (#{...}) on this text, causing NameError: undefined local variable or method 'params' for main:Object.
Resolution: I changed the heredoc definition for the problematic entry in db/seeds.rb from <<~BODY to <<~'BODY' (note the single quotes). This prevents interpolation within that specific string, treating it literally.
Learning: I learned to be cautious when using interpolating heredocs (<<~DELIMITER) in seed files or scripts if the source text might contain #{}, ${}, or similar sequences that could be misinterpreted as code interpolation. Use non-interpolating heredocs (<<~'DELIMITER') or escape the relevant characters (\#{}) within the string if interpolation is needed elsewhere but not for specific literals.

Tags: seeds database ruby heredoc interpolation error debugging workflow

Learned on: April 20, 2024 Edit

CSS changes not reflected (Asset Pipeline/Cache/HTML issue)

Issue: CSS changes I added to application.css for form styling were not reflected in the browser despite server restarts and hard refreshes.
Troubleshooting Steps: I verified CSS file content. Checked browser Network tab (saw 200 OK (from memory cache), indicating stale cache). Ran rbenv exec rails assets:clobber and restarted/refreshed; still no change. Verified stylesheet_link_tag in layout. Verified asset pipeline gem (propshaft). Checked for potential Procfile.dev/manifest.js issues (none found/needed for Propshaft dev). Re-inspected CSS/HTML.
Resolution: I found that the required HTML structure changes (adding classes like form-container, form-group, placeholders) in _form.html.erb were missing/had been reverted. Re-applying the necessary HTML changes resolved the issue.
Learning: When CSS doesn't apply as expected, I learned to double-check *both* the CSS *and* the HTML structure it targets. Asset pipeline issues (caching) can occur, but often the root cause is simpler: the HTML/CSS edits weren't applied correctly or completely in the first place. rails assets:clobber is a key tool for suspected CSS/JS caching issues in development. Propshaft in development typically serves assets directly without complex manifests.

Tags: frontend css debugging asset-pipeline propshaft cache html workflow assets clobber

Learned on: April 19, 2024 Edit

Deployed changes (Edit link) not appearing on Render

Context: A newly added "Edit" link for learnings appeared locally but not on my deployed Render application, despite logs showing the correct commit deployed and server restarted.
Resolution: I modified the Build Command in Render settings. I changed the order of asset tasks from ...; bundle exec rake assets:precompile; bundle exec rake assets:clean; ... to ...; bundle exec rake assets:clean; bundle exec rake assets:precompile; .... Redeploying with clean before precompile made the link appear.
Learning: The order of asset pipeline tasks in the build command matters, especially with tools like Sprockets or Propshaft. I learned that running assets:clean *before* assets:precompile ensures that stale or conflicting assets from previous builds are removed before new ones are generated. This prevents potential issues where old assets (CSS, JS) might be served by the CDN or web server, causing new code changes or UI elements not to appear as expected in the production environment.

Tags: deployment-ci frontend workflow

Learned on: April 19, 2024 Edit

Clarification: Use `./bin/dev` not `rbenv exec bin/dev`

Context: I clarified in README.md that ./bin/dev is the preferred command to start the development server, after confirming rbenv exec bin/dev causes issues (previously logged Apr 8 & Apr 13).
Resolution: I updated README.md to reflect ./bin/dev as the primary command and added a note about specifying the PORT environment variable if needed (e.g., PORT=8000 ./bin/dev).
Learning: I learned to ensure documentation (README.md, PLANNING.md) accurately reflects the working commands discovered during troubleshooting and development, including common variations like specifying a port or necessary environment variables. Keeping documentation consistent with learned best practices for my specific project environment is important.

Tags: workflow documentation readme rbenv bin/dev environment-setup

Learned on: April 15, 2024 Edit

`FactoryBot::DuplicateDefinitionError` on dev server startup

Context: My development server (./bin/dev) failed to boot, reporting FactoryBot::DuplicateDefinitionError: Factory already registered: learning.
Cause: The factory_bot_rails gem was included in the group :development, :test do block in the Gemfile. This caused FactoryBot's Railtie to load factory definitions (spec/factories/*.rb) during development environment initialization (e.g., via Spring or initial boot), potentially conflicting with other initializers or running twice.
Resolution: I moved gem "factory_bot_rails" exclusively to the group :test do block in the Gemfile and ran rbenv exec bundle install.
Learning: I learned that gems intended solely for testing (like factory_bot_rails, shoulda-matchers, capybara) should typically only be included in the :test group in the Gemfile. Including them in :development can lead to unexpected behavior, errors during server startup, or unnecessary loading as their initializers might run inappropriately or cause conflicts.

Tags: testing dependencies factorybot gemfile environment-setup workflow

Learned on: April 15, 2024 Edit

Render: Running initial migrations on free tier (Build Command workaround)

Context: I needed to run initial database migrations (rails db:migrate) on Render's free tier, which lacks Shell access or explicit Pre-Deploy/Post-Deploy command support. Migrations must run after the code is deployed and dependencies installed but before the server starts taking requests based on the new schema.
Resolution (Workaround): I temporarily added bundle exec rails db:migrate to the *end* of the Build Command in Render settings for the first successful deployment (e.g., bundle install; bundle exec rails assets:precompile; bundle exec rails db:migrate).
Learning: On restricted environments (like PaaS free tiers), essential post-deploy tasks like database migrations might need temporary workarounds, such as including them at the end of the build command. I learned to remember to remove the migration step from the build command after the first successful run to avoid unnecessary migrations on subsequent deploys and potentially slow down builds. Considering using release phase tasks if the platform supports them (Render paid tiers do) is a good idea for the future.

Tags: deployment-ci database migration workflow