Verified Commit ebeae8ce authored by doshitan's avatar doshitan
Browse files

Page updates

parent cd215cc0
......@@ -2,7 +2,7 @@
title: Code Review
toc: true
published: 2019-07-28T22:48:15-05:00
modified: 2019-07-28T22:48:15-05:00
modified: 2020-09-24T22:19:41-04:0
---
For me, code review is usually the biggest -- and often most useful --
......@@ -10,35 +10,55 @@ touchpoint between developers. Code changes are the nitty-gritty details, the
rubber actually hitting the road in development work. It can be highly
collaborative and helpful.
Like anything, it can be poorly utilized. And it probably shouldn't be the
*first* touch point for collaboration[fn::There are times when code changes are
the first touch point, they may be the clearest and easiest way to see
something, but often this is not be the case.]; design documents, pairing, etc.
are great ways to share knowledge and build good stuff. But ultimately, changes
to the system have to actually become realized, and that happens through code.
In a professional context, a team should generally prioritize code review.
Everyone should try to get to new requests or feedback as quickly as possible
otherwise the review process can end up spanning a long period of time. This can
lead to a fatigue, more context-switching, and a rush to get things closed and
landed at the end of sprint/deadline.
In my experience, there is typically *at least* one round of feedback->updates
In my experience, there is typically *at least* one round of feedbackupdates
for any non-trivial change.
The [[https://www.gnu.org/philosophy/kind-communication.en.html][GNU Kind Communications Guidelines]] are a good reference for how to
communicate at all levels of the process (and certainly how *I* intend to
conduct myself and what I expect from others).
communicate at all levels of the process.
* Purpose
The point of doing code reviews:
- Build team familiarity with various parts of the code base
- Build broader team knowledge (that is not necessarily related to the
particular code base itself)
- Build the right thing, in the best way
The author is responsible for their work and should be trusted with it. But
ultimately it falls to the team.
It's not about gate-keeping. It's also not a trivial, rubber stamp process.
* As Reviewee
* As Author
Write a good title and description. See my @@html:<a
href="/git#commit-messages">commit message section</a>@@. Reference relevant
tickets and provide context.
If it's a work-in-progress or you are looking for specific feedback on things,
tag it with ~[WIP]~ in the title and state what you are looking for in the
description.
tag it with ~[WIP]~ in front of the title and state what you are looking for in
the description. The project (or team) may have other tags or tagging format,
follow the guidelines.
What I'm looking for and the feedback I provide is different for a design or
architecture review vs something intended to ship immediately.
Include a "test plan" in the description as well. This describes what you did to
verify the changes you are making do what they are supposed to. This helps your
reviewer retrace your steps and also offer suggestions on other considerations
for the changes that perhaps you haven't tested.
Include a "test plan" (or demo) section in the description as well. This
describes what you did to verify the changes you are making do what they are
suppose to. This helps your reviewer retrace your steps and also offer
suggestions on other considerations for the changes that perhaps you haven't
tested.
Hopefully your changes come with some tests as well, and for simple things, the
test plan might be "ran the test suite", but often you'll want to actually
......@@ -49,19 +69,21 @@ of the changes that can't capture adequately in the tests.
testing your changes.
Write [[https://secure.phabricator.com/book/phabflavor/article/writing_reviewable_code/][reviewable code]]. Generally try to keep commit/change sizes small and
focused on one thing. If you find yourself using "and" and "also" in your title
or description that might been your changes could be broken down a little
better[fn::This is something I am continuously working at getting better at. So
often I'll find little things that I fix in the course of some other work that I
really should break out separately, but just include because I'm lazy. Do your
best.].
focused on one thing. If you find yourself using words like "and" or "also" in
your title that might mean the changes could be broken down better[fn::This is
something I am continuously working at getting better at. So often I'll find
little things that I fix in the course of some other work that I really should
break out separately, but just include because I'm lazy. Do your best.].
Take feedback graciously (which has hopefully be given kindly).
Take feedback graciously (which has hopefully been given kindly).
* As Reviewer
Read the title and description. See that it makes sense and you understand what
is trying to be achieved and why we are trying to achieve it. If you don't
understand the goal, don't do go further into it, ask for clarification.
Read the title and description. Ensure they make sense. If the change references
another resource, say a ticket in a separate tracking system. Go read it.
Make sure you understand what is trying to be achieved and why we are trying to
achieve it. If you don't understand the goal, don't go further into it, ask for
clarification.
Hopefully CI is setup that automatically runs linting and tests against all
submitted changes.
......@@ -70,12 +92,13 @@ If automated tooling for linting/formatting/type-checking/building/running tests
are not available, I suggest prioritizing getting that setup, but until then,
pull down the changes and run all that by hand.
If the build is failing, then those need to be fixed before spending time on
reviewing the code, unless the failure has been acknowledged and is being worked
on or help is needed to figure out how to fix it.
If the build is failing, then those need probably need fixed before spending
time on reviewing the code, unless the failure has been acknowledged or is a
place where help is needed to figure out how to fix it.
Deploy the changes to your dev environment, go through the posted test plan and
otherwise exercise the changes to test what you understand the goal to be.
Deploy the changes to your development environment, go through the posted test
plan and otherwise exercise the changes to test what you understand the goal to
be.
You might find it doesn't work as you expect or failure conditions not covered
or the feature is not intuitive/confusing (which might be okay and is
......@@ -87,7 +110,7 @@ Do a quick skim of all the changes. Try to get a big picture view of things.
Then start back at the top and go over every line. Hopefully whatever review
tool you are using (or forced to use) supports building up a set of inline
comments, if not, I suggest take the diff and annotate it yourself as you go.
comments; if not, I suggest to take the diff and annotate it yourself as you go.
Things to keep in mind while providing feedback:
- Address the work, not the person
......@@ -102,22 +125,46 @@ Things to keep in mind while providing feedback:
needs an explanatory comment.
- Point out things you like!
And I'll reiterate, make your intentions clear with feedback. If something is a
suggestion, make sure it's obviously so. If something is a blocker, state that.
If you want a system to follow: https://conventionalcomments.org/
After going over the changes in detail, read over the entire
module/file/document with the changes. Don't get tunnel vision looking only at
the diff. This is most applicable to documentation, where a change in one place
can invalidate some other part and there's limited tooling to help catch it, but
can be helpful with code too. Localized reasoning doesn't work best for
everything, sometimes it's helpful to see the whole thing.
In some code review systems, you can have a "sticky" accept/approve status, so
you can approve the changes with comments about minor things requesting they are
fixed or considered before merging and the author can push up the changes (to
record they were done) and keep the approval to merge without having to get the
record what was done) and keep the approval to merge without having to get the
reviewer to come back.
This is a nice effort saver if it works for your team, sometimes you have folks
that just see "approved" and immediately merge the changes so explicitly
"request changes"/reject even for just a couple minor things helps ensure they
are addressed. Do what works.
This is a nice effort saver if it works for your team. Sometimes there are folks
that see "approved" and immediately merge the changes without looking
for/noticing additional feedback and have a hard time breaking the habit. Do
what works.
Note that this is generally my approach when working with people I have an
established relationship with, that I trust, and are at an equivalent or higher
"level" of experience/ability/etc.
established relationship with, that I trust, and/or are at an equivalent or
higher "level" of experience/ability/etc.
When dealing with contributions from random people (maybe in an open-source
project) or folks that are more junior, more scrutiny and time usually needs to
be taken, being extra clear and precise in wording, linking more reference
project) or folks that are more junior, more scrutiny and time is usually
warranted, being extra clear and precise in wording, linking more reference
material, etc.
And code review does not have to be a thrown-over-the-wall practice, doing a
live walk-through can be good! But generally there's still value in having
someone review the work who a) isn't close to the work and b) who doesn't have
the benefit of the person who wrote it talk through it, since that likely going
to be the situation of folks coming to the code later. Having someone review
with only the written material as reference and note the things that are not
understandable is good.
* Misc.
- https://google.github.io/eng-practices/review/
- https://thoughtbot.com/blog/five-tips-for-more-helpful-code-reviews
- http://mth.io/posts/code-review/
---
title: Git Tips
toc: true
toc-margin: true
published: 2019-04-16T11:23:06-05:00
modified: 2019-08-21T08:26:51-04:00
---
......
......@@ -2,7 +2,7 @@
title: Giving
toc: true
published: 2019-04-16T11:23:06-05:00
modified: 2019-04-16T11:23:06-05:00
modified: 2020-09-24T22:19:41-04:0
---
I'm an advocate for [[https://www.effectivealtruism.org/][Effective Altruism]] and I encourage you to read some of the
......@@ -17,9 +17,7 @@ options. It's your money, and give wherever you believe in, but I'd recommend
giving the majority of your dollars to vetted and effective organizations.
If you are wondering how much to give, there's no absolute answer. Take care of
yourself and your own first. I personally aim to give about 10% of my income.
I'm still working up to this due to work/life things these past few years and
it's generally been around 4%. The number doesn't matter too much, even $5/month
yourself and your own first. The number doesn't matter too much, even $5/month
to a single organization you think does good work is meaningful. And if you shop
at Amazon, be sure to setup and use [[https://smile.amazon.com/about][Amazon Smile]], costs you nothing.
......@@ -34,10 +32,12 @@ or the American branch of orgs. Also this page is currently focused on giving
These are things most people will probably find worth helping.
- [[https://www.doctorswithoutborders.org/][Médecins Sans Frontières/Doctors Without Borders]] (MSF)
- [[https://www.ripmedicaldebt.org/][RIP Medical Debt]]
- [[https://www.givewell.org/][GiveWell]]
- [[https://www.eff.org/][Electronic Frontier Foundation]] (EFF)
- [[https://app.effectivealtruism.org/funds][Effective Altruism Funds]] (some overlap with GiveWell and ACE in certain areas)
- [[https://www.aclu.org/][American Civil Liberties Union]] (ACLU) and your local branch
- [[https://www.feedingamerica.org/find-your-local-foodbank][Your local food bank]]
- Support media creators you like, news sources (such as your local NPR
station), etc., although you may technically get something back for this,
think about things you can be a "patron" for and help out just because you
......@@ -57,7 +57,6 @@ These are areas I find important, but understand others may not agree.
- My local dev group
- [[https://www.patreon.com/bcachefs/overview][bcacefs]]
- [[https://www.patreon.com/pippin/overview][GIMP]]
- [[https://freedom.press/crowdfunding/signal/][Signal]]
- [[https://signal.org/donate/][Signal]]
- [[https://wiki.haskell.org/Donate_to_Haskell.org][Haskell.org]]
- [[https://fund.blender.org/][Blender Development Fund]]
- [[https://www.patreon.com/ofborg][OfBorg]] (NixOS build bot)
---
title: Make Tips
toc: true
toc-margin: true
published: 2019-04-16T11:23:06-05:00
modified: 2019-09-05T22:57:25-04:00
modified: 2020-09-24T22:19:41-04:0
---
I tend to use make as a task runner, a purpose it is not expressly suited to,
but works well enough.
This own site's [[https://gitlab.com/doshitan/doshitan.com/blob/master/makefile][makefile]].
This site's own [[https://gitlab.com/doshitan/doshitan.com/blob/master/makefile][makefile]].
Note I almost always use and build for [[https://www.gnu.org/software/make/][GNU Make]], which is [[#gnu-vs-bsd-make][different in some ways
than other makes]].
......@@ -156,15 +157,17 @@ Disadvantages of make:
For me, a simple makefile strikes a good balance for many projects.
My suggested approach is this:
1. At the beginning, use a simple makefile for common tasks
1. At the beginning, use a simple makefile for common tasks. Whenever you find
yourself needing to run some command (or sequence of commands) more than
once, stick it in your makefile.
2. For bigger tasks, write a standalone script, store it in a ~scripts/~
directory and call the script in the makefile
directory and call the script in the makefile.
3. When you get to the point where you have lots of scripts or some complicated
behavior, write a custom application for managing your project. This might
literally just be a CLI library wrapping some scripts, but it's very nice
having a management interface specifically tuned to your project (and having
a proper programming language to build it in). Use a build system library
like [[https://shakebuild.com/][Shake]] if needed.
behavior, write a custom application for managing your project. This might be
just a CLI library wrapping some scripts, but it's very nice having a
management interface specifically tuned to your project (and having a proper
programming language to build it in). Use a build system library like [[https://shakebuild.com/][Shake]]
if needed.
* Shell tab-complete
Many shells support autocomplete for make targets, zsh ships with support by
default, there is often a ~bash-completion~ package for your system which will
......@@ -324,6 +327,58 @@ make run -- --from here --to there
Generally, if you do need to pass arbitrary arguments to a target all the time,
I would suggest writing a script and running it directly, maybe with make
targets for the common cases. But you do you.
* User defined functions
There are a variety of built-in functions, but it's often useful to define your
own reusable block of code.
You can define "functions" with the [[https://www.gnu.org/software/make/manual/make.html#index-define][~define~ directive]], like so:
#+BEGIN_SRC makefile
define run_thing
do_thing_with_first_arg $(1)
do_another_thing_with_other_arg $(2)
endef
#+END_SRC
The ~define~ directive is just a way to build up a multiline variable, so what
we are really doing is creating a variable. Using a variable to store commands
is also called a [[https://www.gnu.org/software/make/manual/make.html#Canned-Recipes][canned recipe]].
Then to use it, pass it to the [[https://www.gnu.org/software/make/manual/make.html#Call-Function][~call~ function]] in the form of ~$(call
<name_of_function>[,param][,param][,…])~, like so:
#+BEGIN_SRC makefile
$(call run_thing,foo,bar)
#+END_SRC
Which would execute:
#+BEGIN_SRC makefile
do_thing_with_first_arg foo
do_another_thing_with_other_arg bar
#+END_SRC
More concretely, say you wanted to print a test coverage report after every run
of the test suite, as for a Python project using ~pytest~ and ~coverage.py~:
#+BEGIN_SRC makefile
define run_tests
poetry run coverage run --source src -m pytest $(1)
poetry run coverage report
endef
test: ## Run all tests
$(call run_tests,.)
## say this project's convetion is to mark tests that are integration tests, so
## therefore, to run the unit tests, we want to run everything not marked as an
## integration test
test-unit: ## Run just unit tests
$(call run_tests,-m "not integration")
#+END_SRC
Notably the ~call~ function allows us to parameterize the definition (the ~$(1)~
and ~$(2)~ above), which is usually what I need, but if you just want to collect
a few lines that need run as-is in a few places, can just use the function as a
regular variable, e.g., ~$(run_thing)~.
* Auto-documented makefiles
[[https://marmelab.com/blog/2016/02/29/auto-documented-makefile.html][This post]] describes the approach in detail and is quite handy. In sort, annotate
your targets like:
......@@ -339,7 +394,7 @@ help: ## Displays this help screen
@grep -Eh '^[[:print:]]+:.*?##' $(MAKEFILE_LIST) | \
sort -d | \
awk -F':.*?## ' '{printf "\033[36m%s\033[0m\t%s\n", $$1, $$2}' | \
column -ts $$'\t'
column -ts "$$(printf '\t')"
#+END_SRC
And then when you run ~make help~ you get a nicely formatted help page.
......@@ -379,10 +434,10 @@ Then nicely align everything:
┌ table mode, so columns and rows fill correctly
|┌ set separator character between columns
||
column -ts $$'\t'
|└-+-┘
| └ a literal tab character in shell
└ escape the $ for the tab character since we are in make
column -ts "$$(printf '\t')"
|└-----+------┘
| └ get a literal tab character
└ escape the $ for the tab character since we are in make
#+END_SRC
I use a tab character to separate the target and help text as it's unlikely to
......@@ -785,3 +840,5 @@ help: ## Displays this help screen
* Misc.
- http://clarkgrubb.com/makefile-style-guide
- http://make.mad-scientist.net/papers/rules-of-makefiles/
- https://blog.mindlessness.life/2019/11/17/the-language-agnostic-all-purpose-incredible-makefile.html
- http://gromnitsky.users.sourceforge.net/articles/notes-for-new-make-users/
---
title: Nix Tips
toc: true
toc-margin: true
published: 2019-08-21T08:25:45-04:00
modified: 2019-09-05T22:54:28-04:00
---
......
---
title: Shell
toc: true
toc-margin: true
published: 2019-04-16T11:23:06-05:00
modified: 2019-08-21T08:27:38-04:00
---
......
......@@ -2,7 +2,7 @@
title: Uses This
toc: on
published: 2015-04-01T17:49:21-05:00
modified: 2019-04-16T11:23:06-05:00
modified: 2020-09-24T22:19:41-04:0
---
There's a neat series of interviews at [usesthis.com](http://usesthis.com/) and
in generally I like seeing what other people use to do stuff. So here's some of
......@@ -40,8 +40,9 @@ mine.
# Software
* [doom-emacs](https://github.com/hlissner/doom-emacs)
* tmux
* zsh ([my config](https://gitlab.com/doshitan/dots-zsh))
* [doom-emacs](https://github.com/hlissner/doom-emacs) ([my config](https://gitlab.com/doshitan/dots-emacs/-/tree/doom/.doom.d))
* tmux ([my config](https://gitlab.com/doshitan/dots-tmux/-/blob/master/.tmux.conf))
* make (for things I should probably use shell scripts for)
* KeePass family of things to manage passwords
- Linux: [KeePassXC](https://keepassxc.org/)
......@@ -50,6 +51,7 @@ mine.
* nix and NixOS for everything I can
* Fastmail for email, calendar and contacts
* Mullvad for VPN
* GNOME desktop environment
# Writing Stuff
......@@ -62,8 +64,8 @@ mine.
## Pens
* Lamy Safari (in Charcoal with EF, F, M, B, and 1.1mm nibs, EF used the most)
* A few Reform 1745s
* Parker 51 Aeromatic (grey body/silver cap)
* Noodlers Ahab (in Amazon Pearl)
* Parker 51 Aerometric (grey body/silver cap)
* Noodler's Ahab (in Amazon Pearl)
* Jinhao X450 (in Black/Gold)
* Pilot Metropolitan x 2 (in Black M and Silver F)
* Pilot Plumix (~1mm stub)
......@@ -73,20 +75,36 @@ mine.
* Pilot Vanishing Point, in matte black with F nib
* Moonman M2, F
* TWSBI Eco Clear, F
* Montblanc SlimLine, B (in black)
The only non-fountain pens I keep around and use are Uni-Ball Jetstreams.
## Ink
* Noodler's Sequoia Green, practically all I use currently
* Noodler's Cactus Green
* Noodler's Bulletproof Black
* Aurora black
* Mont Blanc Lavender Purple
* [Noodler's Sequoia Green](https://noodlersink.com/product/19025-sequoia-green/)
- The first ink I truly loved. Wrote with it almost exclusively for years.
* [Noodler's Cactus Green](https://noodlersink.com/product/19204-eel-gruene-cactus/)
- A lubricated ink, so sees very little use, but if a piston is a little
sticky and I don't want to take the pen apart, switching to this ink can
help.
* [Noodler's Bulletproof Black](https://noodlersink.com/product/19001-black/)
* [Noodler's 54th Massachusetts](https://noodlersink.com/product/19071-54th-massachusetts/)
* [Noodler's Black Swan in Australian Roses](https://noodlersink.com/product/19065-black-swan-australian-rose/)
* [Aurora black](https://www.aurorapen.it/en/prodotto/black/)
- I believe this was the first ink I ever bought.
* Montblanc Lavender Purple
- Discontinued. Replaced by [Amethyst
Purple](https://www.montblanc.com/en-us/ink-bottles_cod34480784411722503.html),
which is very similar.
* [J. Herbin Emerald of Chivor](https://www.jherbin.com/1670.html)
(these are only the inks I have as a bottle, _many_ other samples are sitting around)
## Paper
* Nanami Seven Seas notebooks (A5)
* Muji B6 recycled notebooks (plain)
* Leuchtturm 1917 notebooks (dotted in A5 and Pocket)
* Clairefontaine Triomphe (A5), for correspondence
* HP LaserJet Paper
* HP Premium24 printer paper (formerly branded as LaserJet)
# Music stuff
......
......@@ -3,7 +3,7 @@ title: Vegan Things
toc: true
toc-margin: true
published: 2018-12-30T17:05:31-06:00
modified: 2020-01-19T23:20:08-0500
modified: 2020-09-24T22:19:41-04:0
---
> Veganism is a way of living which seeks to exclude, as far as is possible and
......@@ -29,6 +29,7 @@ Some might resonate with you and others might not.
## Books
- [Animal Liberation](https://www.goodreads.com/book/show/29380.Animal_Liberation) by [Peter Singer](https://petersinger.info/)
- The argument is the first chapter, about twenty pages, so that's all you have to read for the why.
- [Eating Animals](https://www.goodreads.com/book/show/6604712-eating-animals) by [Jonathan Safran Foer](https://en.wikipedia.org/wiki/Jonathan_Safran_Foer)
- [The Sexual Politics of Meat: A Feminist-Vegetarian Critical Theory](https://www.goodreads.com/book/show/51714.The_Sexual_Politics_of_Meat) by [Carol J. Adams](https://caroljadams.com/)
- [Eat Like You Care](https://www.goodreads.com/book/show/18138630-eat-like-you-care) by [Gary Francionne](https://www.abolitionistapproach.com/)
......@@ -55,6 +56,8 @@ by Mercy for Animals is a good intro/overview of a lot of things.
The aptly named [vegan.com](https://www.vegan.com/) is a solid and quick
reference resource. I'd skim the headings to get an idea of what's there.
If you want a structured, 30 day guide, you could try https://veganbootcamp.org/.
My biggest suggestion is to not find/make vegan versions of your favorite food,
at least at first. Instead, explore new food, from cultures maybe you haven't
really dived into; eat food that is naturally vegan and isn't trying to be
......@@ -492,7 +495,9 @@ usually something like this.
Whether it's just the taste or reminds them of childhood or their culture.
Someway, somehow, the consumption of animal products makes them feel good.
So does heroin, I hear.
So does heroin, I hear.^[In case it needs said, please don't ever "try" heroin.
[Internet folktale of
warning](https://old.reddit.com/user/SpontaneousH/submitted/?sort=new).]
That's a little glib, but the point being there are other things that feel good
in life and things to consider beyond your own personal enjoyment, particularly
......@@ -849,3 +854,4 @@ videos for more.
# More resources
- [TalkVeganToMe](https://talkveganto.me/en/)
- https://vegancheatsheet.org/
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment