Saturday, April 4, 2020

why implementing a single feature took 12 hours

Yesterday I started investigating how to get d3.js working for the Physics Derivation Graph.  I already had an implementation working on the live website, so I didn't expect the update to take too much effort or time.

Below is the sequence of challenges I encountered for this feature update.
  1. I learned that I had used v3; the current version is v5
  2. v5 doesn't support the .force() used in v3
  3. I found a v5-based force directed graph on https://observablehq.com/@d3/force-directed-graph
  4. Although I was able to get the code running locally, I found the files seemed to depend on remote resources. 
  5. I found a better instance that was pure d3.v5.js instead of relying on observable code: https://bl.ocks.org/mapio/53fed7d84cd1812d6a6639ed7aa83868
  6. Figured out how to get images associated with nodes
  7. The JSON file needs images to have distinct and consistent names
  8. Instead of temporary image file names, use expr_global_id and expr_name
  9. The functions using "return False, error_message" meant the errors didn't propagate to the web interface. The "right" method is to use "raise Exception" 
  10. With exceptions raised in compute, needed to add "try/except" in controller.py
  11. With Exceptions caught in controller.py, use flash() to tell the user there was a problem
  12. With Exceptions now sent to user via web interface, I learned that the PNG wasn't being created due to a missing command, "braket"
  13. I found that "braket" is a latex package available from CTAN
  14. I tried to install "braket" using "tlmgr install"; see https://tex.stackexchange.com/questions/73016/how-do-i-install-an-individual-package-on-a-linux-system
  15. I wasn't able to run "tlmgr" in Docker due to not having wget
  16. I wasn't able to install wget in Docker using "apt-get install -y wget", possible due to using phusion as a base image?
  17. Looked up instructions on installing packages manually; opened https://github.com/allofphysicsgraph/proofofconcept/issues/82
  18. In the process of debugging the PDF generation (notice that I strayed from the d3js effort), realized the migration of inference rules was incomplete -- new style is to have words separated by spaces in create_tmp_db.py
  19. Added an exception in compute.py to identify inconsistent inference rule names
  20. Manually fixed inference rule entries in create_tmp_db.py
  21. Altered the inference rule schema in compute.py -- use feeds+inputs+outputs
  22. Manually updated inference rules in create_tmp_db.py to reflect revised schema
  23. Compiling derivation PDF failed due to incorrect implementation of inference rule
  24. Realized that the "braket" issue wasn't a missing package, it was custom macros defined in an old version of the PDG
  25. Wrote function to generate JSON needed for d3js
  26. In the process of iterating that, added page latency measurement
Lessons learned:
  • In the process of implementing a new feature or updating a feature, I uncovered a few bugs and a lot of technical debt that lead to the implementation taking longer than expected
  • Some of the bugs were easy to fix (aka buy down the tech debt) as I discovered them, while others were sufficiently worthy of a new ticket. 
  • Some bugs were blockers -- I couldn't proceed with the desired work until I resolved architecture flaws; other issues were tangential and could be delayed.

No comments:

Post a Comment