GitHub links

My GitHub-related links

• https://salewski.github.io (this page)
• https://github.com/salewski
• https://avatars.githubusercontent.com/u/997214?v=3 (github avatar img url)
  

GitHub Developer

• https://developer.github.com/program/
• https://developer.github.com/guides/
• https://developer.github.com/changes/
• https://developer.github.com/v3/
• https://developer.github.com/libraries/ (Octokit and friends)

My GitHub Pages cheatsheet

    $ cat - < Gemfile
    source 'https://rubygems.org'
    gem 'github-pages', group: :jekyll_plugins
    EOF

    $ # This will install (into the 'local-ruby-gems' subdir) the direct dependencies specified in the above 'Gemfile', along with all of their (transitive) dependencies.
    $ bundle install --path=./local-ruby-gems --verbose

    $ cat - < _config.yml
    title: CHANGE-ME-MY-PROJECT-NAME by Alan D. Salewski
    description: CHANGE-ME-ONE-LINE-DESCRIPTION

    # See also: https://milanaryal.com/2015/writing-on-github-pages-and-jekyll-using-markdown/
    #           https://github.com/blog/2100-github-pages-now-faster-and-simpler-with-jekyll-3-0
    #
    markdown: kramdown
    kramdown:
      input: GFM # Enable GitHub Flavored Markdown (fenced code blocks)
      hard_wrap: false
    highlighter: rouge

    exclude:
      - local-ruby-gems/  # avoid processing jekyll itself; see also: https://github.com/jekyll/jekyll/issues/2938
    EOF

    $ bundle exec jekyll serve --watch

Q: Should I check the 'Gemfile in'?
A: Yes, and check in the 'Gemfile.lock' file, too, while you're at it.
See also:

• http://bundler.io/rationale.html#checking-your-code-into-version-control
• https://jekyllrb.com/docs/github-pages/
• https://help.github.com/articles/using-jekyll-as-a-static-site-generator-with-github-pages/
• https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/
• http://www.stephaniehicks.com/githubPages_tutorial/pages/githubpages-jekyll.html
• http://programminghistorian.org/lessons/building-static-sites-with-jekyll-github-pages

    $ git checkout --orphan gh-pages
    Switched to a new branch 'gh-pages'

    $ git rm -fr .
    
    $ git status
    On branch gh-pages

    No commits yet

    nothing to commit (create/copy files and use "git add" to track)

    $ cat - <<EOF > Gemfile
    source 'http://rubygems.org'
    gem 'github-pages', group: :jekyll-plugins
    EOF

    $ bundle install --path=./local-ruby-gems --verbose

    $ cat - <<EOF > _config.yml
    title: my-project-name by Alan D. Salewski
    description: blah blah blah

    markdown: kramdown

    kramdown:
        input:     GFM  # Enable GitHub Flavored Markdown (fensed code blocks)
        hard-wrap: false

    highlighter: rouge

    exclude:
        - local-ruby-gems/    # avoid processing jekyll itself; see also https://github.com/jekyll/jekyll/issues/2938
    EOF

    $ bundle exec jekyll serve --watch
    Configuration file: /path/to/project/_config.yml
    Configuration file: /path/to/project/_config.yml
                Source: /path/to/project
           Destination: /path/to/project/_site
     Incremental build: disabled. Enable with --incremental
          Generating...
                        done in 0.389 seconds.
     Auto-regeneration: enabled for '/path/to/project'
    Configuration file: /path/to/project/_config.yml
        Server address: http://127.0.0.1:4000/
      Server running... press ctrl-c to stop.

    $ bundle exec jekyll serve --watch --drafts
    Configuration file: /path/to/project/_config.yml
    Configuration file: /path/to/project/_config.yml
                Source: /path/to/project
           Destination: /path/to/project/_site
     Incremental build: disabled. Enable with --incremental
          Generating...
                        done in 0.639 seconds.
     Auto-regeneration: enabled for '/path/to/project'
    Configuration file: /path/to/project/_config.yml
        Server address: http://127.0.0.1:4000/
      Server running... press ctrl-c to stop.

    $ git mv _drafts/my-article.md _posts/writings/YYYY-MM-DD-my-article.md

    $ git push --follow-tags origin master
    ...

    /etc/apt/preferences.d/LOCAL-avoid-systemd.pref

    Package: systemd-sysv
    Pin: release o=Debian
    Pin-Priority: -1

• -~.-~.-~.-~.-~.-~.-~.
• title: Terraform HOWTO: delete a non-empty AWS S3 bucket
• url: /2017/04/30/terraform-howto-delete-a-non-empty-aws-s3-bucket.html
• date: 2017-04-30 00:00:00 +0000
• id: /2017/04/30/terraform-howto-delete-a-non-empty-aws-s3-bucket
• categories:
• tags: awscloud-architecturehowtoinfrastructure-as-codes3terraform
• path: _posts/writings/2017-04-30-terraform-howto-delete-a-non-empty-aws-s3-bucket.md
• previous:
  Alan D. Salewski (writings)

  Al's GitHub Pages with Jekyll cheatsheet

  Jun 18, 2016

  (Updated: 2020-05-05 to add notes on creating the orphan ‘gh-pages’ branch)

  Preliminaries

  Create an “orphan” git branch named ‘gh-pages’

  GitHub Pages will allow you to publish your project’s site from a few different “sources”. Here we are concerned only with one of those approaches: an “orphan” git branch named 'gh-pages' within the repo.

  The name 'gh-pages' is not optional; it is treated specially by GitHub Pages. You cannot choose an arbitrary branch name from which to publish your project’s site; the branch must be called 'gh-pages'.

  Note that your project’s settings page in the GitHub web site will only show the 'gh-pages' branch as an option in the GitHub Pages “Source” drop-down if the branch already exists in your project’s repository.

  For the purposes of publishing your project’s site on GitHub Pages, you’ll want the 'gh-pages' branch to be an “orphan”. That is, you want it to have a history that is entirely disconnected from the other existing branches in your repository. To achieve that, we are going to use the --orphan option to git-checkout(1):

      $ git checkout --orphan gh-pages
      Switched to a new branch 'gh-pages'
  

  At this point, a git status would show that all of the repo’s files that were being tracked on the branch source point are now staged in the index; git does this in anticipation of the user wanting to create a new, clean go-forward history for the “as is” state of the files. That is not our use case, however; we are going to use an entirely different set of files on our new branch, so we can just clear out the git index:

      $ git rm -fr .
      
      $ git status
      On branch gh-pages
  
      No commits yet
  
      nothing to commit (create/copy files and use "git add" to track)
  

  Now you have a clean 'gh-pages' branch with no commits. Read on to see how we want to populate it, starting with a file named 'Gemfile'.

  Install Jekyll and other related Ruby-based tooling

  In your brand new working directory for a site you intend to generate with Jekyll and host with GitHub Pages, you will want to have some tooling available locally to allow you to veiw the Jekyll-based site generation prior to pubishing it on GitHub Pages.

  The Jekyll software is written in Ruby, and (as is true of most Ruby software) is released in the form of a “gem”.

      $ cat - <<EOF > Gemfile
      source 'http://rubygems.org'
      gem 'github-pages', group: :jekyll-plugins
      EOF
  

  This will install (into the 'local-ruby-gems' subdir) the dependencies specified in the 'Gemfile' (see Gemfile(5)), along with all of their dependencies.

      $ bundle install --path=./local-ruby-gems --verbose
  

  
      $ cat - <<EOF > _config.yml
      title: my-project-name by Alan D. Salewski
      description: blah blah blah
  
      markdown: kramdown
  
      kramdown:
          input:     GFM  # Enable GitHub Flavored Markdown (fensed code blocks)
          hard-wrap: false
  
      highlighter: rouge
  
      exclude:
          - local-ruby-gems/    # avoid processing jekyll itself; see also https://github.com/jekyll/jekyll/issues/2938
      EOF
  

  Regular usage

  Prior to publishing: edit -> review -> commit cycle

  Once you have your tooling setup in your project’s git working directory, you will basically just edit the Markdown files of individual articles in the '_drafts' subdirectory. The edit -> review -> commit cycle works almost the same as any other software project, with commits happening wherever makes sense for the particular article content.

  The “review” phase mainly involves just rereading the article content and making adjustments as necessary. Before committing, however, you should view the Jekyll-rendered form of the article in your web browser. To do that, you could just 'git push' to GitHub Pages and hope for the best, but since you’ve gone through the trouble of setting up your local Jekyll-based tooling you should launch the local web server built into Jekyll for previewing your changes.

  This will generate the static site and render it the way it will be published when you 'git push ...' your changes up to GitHub:

      $ bundle exec jekyll serve --watch
      Configuration file: /path/to/project/_config.yml
      Configuration file: /path/to/project/_config.yml
                  Source: /path/to/project
             Destination: /path/to/project/_site
       Incremental build: disabled. Enable with --incremental
            Generating...
                          done in 0.389 seconds.
       Auto-regeneration: enabled for '/path/to/project'
      Configuration file: /path/to/project/_config.yml
          Server address: http://127.0.0.1:4000/
        Server running... press ctrl-c to stop.
  

  The following variation of the same command (adds the '--drafts' option) will generate the static site and render it with all of your unpublished drafts integrated into the site:

      $ bundle exec jekyll serve --watch --drafts
      Configuration file: /path/to/project/_config.yml
      Configuration file: /path/to/project/_config.yml
                  Source: /path/to/project
             Destination: /path/to/project/_site
       Incremental build: disabled. Enable with --incremental
            Generating...
                          done in 0.639 seconds.
       Auto-regeneration: enabled for '/path/to/project'
      Configuration file: /path/to/project/_config.yml
          Server address: http://127.0.0.1:4000/
        Server running... press ctrl-c to stop.
  

  In addition to the normal posts (everything beneath the '_posts' subdir), the above command also includes everything beneath the '_drafts/' subdir.

  Q: Should I check the Gemfile in?

  (Concerned that it might have an adverse effect if interpreted by the remote GitHub site builder.)

  A: Yes, empirical testing shows that the remote site builder does not break.

  Publishing

  Once you are happy with the content of an article, you can cause GitHub Pages to render it by moving it from the '_drafts/' subdir to the '_posts/writings/' subdir, with a publication date embedded in the file name:

      $ git mv _drafts/my-article.md _posts/writings/YYYY-MM-DD-my-article.md
  

  Push your locally committed changes to GitHub to have them rendered by GitHub Pages:

      $ git push --follow-tags origin master
      ...
  

• next:
  Alan D. Salewski (writings)

  Debian 9.x "stretch" APT pinning change

  Jun 25, 2017

  Last week (on 2017-06-17), Debian GNU/Linux 9.x (codenamed “stretch”) was released. While preparing to update one of my systems I came across the following statement in section 5.3.2.2 of the release notes (“New requirements for APT repository”):

  5.3.2.2. New APT pinning engine

  APT 1.1 introduced a new pinning engine that now matches the description in the manual page.

  The old engine assigned one pin priority per package; the new one assigns pin priorities per version. It then picks the version with the highest pin that is not a downgrade or that has a pin > 1000.

  This changes the effect of some pins, especially negative ones. Previously, pinning a version to -1 effectively prevented the package from being installed (the package pin was -1); it now only prevents the version of this package from being installed.

  I run my Debian systems without systemd, and my initial reading of the above text gave me pause because I use APT pinning to prevent systemd from becoming my init system. My initial reading of the above left me with the misunderstanding that I would need to apply a different mechanism to keep my current init setup ('/sbin/init' provided by sysvinit-core package).

  The default init system on Debian (since Debian 8.x, codenamed “jessie”) has been systemd, in which '/sbin/init' is provided by the systemd-sysv package. This continues to be the case with Debian 9.x.

  My existing setups use a customized set of APT preferences which, among other things, contains the file:

      /etc/apt/preferences.d/LOCAL-avoid-systemd.pref
  

  whose meat is:

      Package: systemd-sysv
      Pin: release o=Debian
      Pin-Priority: -1
  

  The effect of the 'Pin-Priority' of -1 is to prevent APT from ever installing the 'systemd-sysv' package. And indeed, this is how the mechanism continues to work in Debian 9.x “stretch”. I did not realize this without closer study, however.

  After spending more time than I care to admit searching for and reading related info on the ‘Net, I came to realize that the statement in the release notes above applies very specifically to how APT treats pinning of versions. The above APT configuration, in contrast, is based on the separate concept of release origin.

  The above config file snippet applies the -1 pin priority to any 'systemd-sysv' package in which the “Release file” declares the origin as “Debian” (the release o=Debian bit). It does not contain any bits related to the package version.

  In retrospect, this is all rather obvious, and I’m embarrassed to think how much time I spent researching it. It was also quite helpful to read the motivation for the release notes blurb, which is contained in bug #852967, against the ‘release-notes’ pseudo-package.

  Other than mucking around with my 'sources.list' file (and related), I tend to go many years between having to think about my APT configuration at all – so it is easy to become hazy on the details. Hence my focus on the -1 pin priority but glossing over the specific language in the release notes of “pinning a version” (which it is now clear that I am not doing).

  I hope the above saves somebody from the need to research the same concerns I had.