bitcoin-core-review-club / website

Bitcoin Core PR Review club website

bitcoin-core-review-club

Simple Jekyll site for hosting the Bitcoin Core PR Review club at https://bitcoincore.reviews/.

Development

You'll need Ruby and Jekyll to run the site locally. Ruby 2.6 is recommended. Once they are set up:

• Clone the repository and go into the directory
• Run bundle install
• Run make preview
• Go to http://localhost:4000

In case of any issues, don't hesitate to run the following to update rubygems, bundler, and dependencies: gem update --system && gem update && bundle update

Making a new post

See the hosting.md doc for how to create a post for an upcoming meeting.

Changing Site Data

All site configurations are either contained in _config.yml or _data/settings.yml. Some data is duplicated between the two due to the way Jekyll injects variables, so be sure to update both.

Running the Test Suite

To run all tests: rake test or just rake

To run one test file: rake TEST=test/test_site_content

To run an individual test in a test file: rake TEST=test/test_site_content TESTOPTS=--name=test_site_displays_no_empty_nicks

Before running tests for the first time, you may need to run bundle update.

Before running the test_all_links test (or all of the tests, which includes it), the site needs to be started up locally with make preview, or with make clean preview if any meeting logs were changed, to pre-render the logs through the auto_logs_markup plugin.

Attributions

Thanks to LeNPaul for the Jekyll starter kit this was forked from and to Will O'Beirne for pointing me in that direction.

website's Issues

Clarify purpose of IRC meetings

@miketwenty1 mentioned that it's not immediately obvious what the purpose of the IRC is when arriving at the landing page: https://bitcoincore.reviews/. There is some rationale ("The point of the review club is to give participants..." but it's a bit vague and buried in the middle of the text).

Mike - perhaps you could suggest some alternative text?

Missing Chatlog

Does someone still have the log for https://bitcoin-core-review-club.github.io/15759.html? I sometimes go back to old sessions to lookup stuff, and this PR was really interesting.

Meeting listings suggestions

As a follow-up to #28:

• Name them "Meetings" or "PR Reviews" instead of "Previous Meetings", and list all of the meetings, not just previous ones.

• On the Meetings by date listing, consider breaking up the growing list a bit by adding some space (css padding) between months.

add id attributes to meeting logs

I've summarized a previous Review Club meeting for the Optech newsletter (here: bitcoinops/bitcoinops.github.io#366 (comment)). For those summaries, it'd be really useful to be able to link specific lines in the meeting log. For that we'd need id or name attributes for each line.

@ajttowns bot does that automatically, eg http://www.erisian.com.au/bitcoin-core-dev/log-2020-03-10.html#l-3. Perhaps it's time to start doing something a bit smarter than copy-pasting meeting logs so we can add more structure to the logs.

Token generat

Exporting site content as pdf

This site is one of the best resources on the internet to learn about the Bitcoin Core. Why not having its content as a pdf file format? Having it as a pdf, makes its content more portable and easier to read. Personally sometime I wanted to read site's notes offline but it wasn't possible.
We can develop a python script to read data from _posts directory and generate a pdf file as output. So every week someone can pull recent commits from repository and run the script, and enjoy having the latest version of the pdf, containing all notes and discussions of bitcoin-core-review-club.
Furthermore, we can add the script in github workflows, and set it to be run by every merge to master and uploading the file. Thus we have always the latest version of pdf available in the repo.

Help

          Help

Originally posted by @Ronnie6464 in #688 (comment)

Wishlist: related PR review clubs section

For the review clubbies who consume meetings like youtube videos, I wish we had a section at the end of meetings for "related PR review clubs."

I think it's nice to link to other review clubs we've done on the same topic (e.g. Minisketch/Erlay, coin selection, deployments). But it's unmaintainable if it requires the host/someone to remember all past review clubs. I think the best approach would be to (optionally) tag meetings with a topic from a list of topics in the preamble (more specific than the component groupings, perhaps can correspond to optech topics). That way we can tear down with a quick sed script if we change our mind.

Rename repo

We now use netlify to host this site instead of github pages. If the repo is named <org>/<org>.github.io, then github will automatically try to build it as a github page. That no longer works for this site since we're using a custom plugin, so I get these notifications:

[bitcoin-core-review-club/bitcoin-core-review-club.github.io] Page build failure

The page build failed for the master branch with the following error:

The tag irc on line 3 in _posts/2019-05-01-#15557.md is not a recognized Liquid tag. For more information, see https://help.github.com/en/github/working-with-github-pages/troubleshooting-jekyll-build-errors-for-github-pages-sites#unknown-tag-error.

For information on troubleshooting Jekyll see:

https://help.github.com/articles/troubleshooting-jekyll-builds

If you have any questions you can submit a request on the Contact GitHub page at https://support.github.com/contact/pages?repo_id=185674396&page_build_id=170390927

I think the easiest way to spare myself these emails is to rename the repo to something like website.

I'll do that in the next couple of days unless anyone complains.

Color-code meeting participants

We render all meeting participants in the same color. A couple of people have suggested to me that each participant should have a separate color to make it easier to follow threads. Not sure how much effort it'd be to implement it or how useful in general, but I'm opening this issue to track that request.

currently:

proposed:

Future PRs

Please comment in this issue to request PRs to be covered in future review club meetings.

Remove third party downloads

The default theme I use ends up fetching various style/script files from CDNs and third parties. We should remove those.

Add "https://bitcoincore.reviews/" as GitHub project URL attribute

The URL is right next to the project description on GitHub

Gemfile missing from the repository

The Gemfile needs to be present for bundle install to function. The usual practice would be to commit it in the repository.

Add component and host indexes

After #21, each PR page will have a component and host tag. Add per-component and per-host index pages so interested users can look for all PRs by a component. I expect the URL scheme will be eg https://bitcoin-core-review-club.github.io/component/wallet, https://bitcoin-core-review-club.github.io/host/jonatack, etc

Change Meeting Pace

We currently do meetings weekly. Here are a few observations and disadvantages:

• For attendees, it's difficult to prepare every single week. It's also easy to decide to skip a week, since there will be another in 7 days.
  • There has been a clear decline in attendance over the past year or so.
• We often don't have enough time to dive into the PR at a deeper level. Meetings often only cover the basics. When we do two-parters, many people have forgotten about the PR by the next week.
  • This can also come from the fact that notes aren't posted early enough so people don't have time to prepare.
  • I imagine the surface-level discussion also deters people from attending.
• This structure also doesn't encourage people to review consistently. I see a lot of "Concept ACK" from review club and then no further reviews. This isn't the ideal PR review process and I imagine it is frustrating for the authors as well.
  • I observe this most commonly in myself, not trying to just criticize others. My list of "half-reviewed PRs" is extremely long (for many reasons I'll admit, but it's not helped by the need to devote time to a new PR every week).
  • We never intended to use review club to "get things merged," but the goal is to teach people how to review PRs and dig into the codebase. Consistency and depth are part of that.
• It's difficult to find hosts every week. Stephan and Larry have been regularly hosting, but it's quite common for Stephan or me to host back-to-back. I once had to host 4 in a row. Notes/questions increasingly require our attention on weekends. I've been burning out for months and luckily Stephan has picked up my slack (thank you 🤗) but this is unsustainable.
  • More volunteers to host is nice, but difficult to rely on. Reviewing notes, attending meetings, and posting logs still requires minimum 2 hours every week.
  • It's very difficult to justify this given the low attendance. There is currently a big asymmetry in the amount of work Stephan and I put in vs. the amount of learning time for people who use this meeting as an educational resource.

Ideally:

• Attendees and hosts are excited about each PR and have ample time to prepare for the meeting.
• During the meeting, all questions are welcome, but we really dig into the PR. Attendees really review the PRs in depth and consistently, experiencing more than just the "concept ACK" stage.
• We do not burn out.

Proposal:

• Reduce the frequency to 1 PR per month
  • We could also perhaps do 2 per month, e.g. the 1st and 3rd wednesdays
  • "every other week" doesn't work because it's really easy to forget which week is a review club week, for both hosts and attendees.
• Instead of a single 1hr meeting weekly, 2 meetings on the same week. The first meeting covers concept/approach, and the second meeting is implementation and code (or something).
  • e.g. wednesday 17UTC and thursday 11UTC.
  • maybe multiple times will help accommodate people in different timezones!
  • We can cover bigger PRs more thoroughly without leaving 7 days in between to lose attention
• We won't necessarily meet for less time (e.g. if we do 2 per month), just changing the pace.

Listings improvements

From @jonatack (#21 (comment))

A couple of future ideas:

• Add the host link to the listings, along with column headers Date / Host / PR.
• To make the variable width of the date columns not mess up vertical alignment (noticeable in the new previous meetings page), adopt a fixed-width font or use an HTML table or similar markup.

Add RSS feed for announcements, notes, logs

Instead of having people rely on Twitter or announcements in the IRC channel, I think having an RSS feed would be nice?

The most naive approach is to push an update for any change to the _posts/ dir, or perhaps more elegantly could also allow people to individually subscribe to announcements, questions/nodes, and logs updates.

Found e.g. https://github.com/jekyll/jekyll-feed which seems to also supports tagging.

Can't link to the Meeting 2 log lines (for Optech)

The monthly Review Club section of the Optech newsletter wants to link to specific lines of the Meeting Log. This works fine for Meeting 1, but the log line numbers for Meeting 2 start again at 1, and those line numbers (which are links) bring you back to the corresponding line number in Meeting 1. So there doesn't seem to be a way to link to lines in the Meeting 2 log.

To see the problem, click on one of the Meeting 2 line numbers here: https://bitcoincore.reviews/28122

An obvious solution would be to not restart the line numbers at Meeting 2, just let them continue where they left off at the end of Meeting 1.

I don't know if there's a way to fix this particular document (28122) quickly, but the Optech write-up is due in the next day or two (sorry about reporting this so last-minute).

I'll ask Dave Harding if we could push the Review Club section until next week; we've done that before, so it shouldn't be a problem. That will allow an extra week to fix this. I'll report back here when I get a reply from Dave.

Add a Glossary or something similar

It's perhaps worth keeping a glossary so we don't have to continuously re-define things like ancestor feerate, block-relay-only connections, effective fees in coin selection, etc. We sometimes link to previous review clubs, but that also doesn't offer a direct definition. Maybe something similar to bitcoinops topics (so it's easily linkable and back-linkable) but for low-level terms.

PSA: new Gemfile dependency kramdown-parser-gfm

I'm currently using Ruby 2.6.6p146 (2020-03-31) with this repo (and so an updated Gemfile.lock as well), so this may or may not affect anyone using a different major version like Ruby 2.5.x, but here's a quick public service announcement, if helpful:

To run make preview, I needed to add the following line to the Gemfile and run bundle update:

diff --git a/Gemfile b/Gemfile
index 71b0ef9..52bd101 100644
--- a/Gemfile
+++ b/Gemfile
@@ -8,6 +8,7 @@ gem "jekyll-paginate", "~> 1.1"
 gem "jekyll-sitemap", "~> 1.3"
 gem "jekyll-feed", "~> 0.12.1"
 gem "jekyll-seo-tag", "~> 2.6"
+gem "kramdown-parser-gfm"

Save a tagged commit of PR branch at meeting time

Often, the PR branch will change after we've run review club. That's bad for our archives because:

• any links to commits in the previous version of the PR branch will become dead after the branch is garbage-collected by github.
• discussion in the meeting log might not make sense in retrospect if the PR changes a lot after the meeting.

One solution is to make a fork of bitcoin at bitcoin-core-review-club/bitcoin and then tag the PR branch before the review club, and use that tagged branch for all links. As a tagged branch in that repo, it'll persist and the links will stay live.

dark mode

hi @glozow

would you accept a PR that enables dark mode for users whose operating system indicates prefers-color-scheme:dark ?

i'd be happy to take a look at that