DEV Community: Oliver Pham

How My View on Open Source Has Changed

Oliver Pham — Sat, 11 Dec 2021 04:33:14 +0000

In the first blog that I wrote about open source, there was one thing I wanted to know about it:

I heard a lot about the glamorous evolution that most programmers experience while contributing to open source projects. Everything from their technical skills (e.g. programming knowledge, coding style) to their soft skills (e.g. collaboration and communication skills) is improved.

Without too much spoiling, I can say that I came looking for gold, but I found diamond instead. With only 14 weeks, I feel that there are still quite a lot of aspects about open source that I haven't experienced yet. Nevertheless, I won't let it stop me from sharing my personal experience.

Supportive Community

There is one thing I can say for sure: I love the spirit of open source. I've had a wonderful time working with open source communities of different sizes (e.g. Seneca-CDOT, StepZen, Appwrite, and Zulip). Fortunately, all of them are fantastic and patient with beginners.

Amazing opportunity to learn

I've had several good opportunities to learn not only new technologies but also good software development practices. I helped Element fixed a CSS bug but made a few mistakes when submitting my pull request. During Hacktoberfest, I picked up two completely new technologies (i.e. Ruby and GraphQL) and a nice tree for my 4 merged pull requests. I also had an opportunity to work with Docusaurus while auditing the content of IPC144 Course Notes. Finally, I will never forget my struggle to develop a new feature with jQuery and Handlebars for Zulip.

What Open Source really is

After all that, it's still hard to tell if my skills have improved any bit. Nevertheless, I realized in the end it doesn't really matter (thanks Linkin Park for reminding that). In my opinion, open source is all about publishing your "bad" code/project and collaborating with others to improve it. I don't mean "bad" as in "worth being shamed and disrespected". It's the "bad" in "worth being improved/enhanced/optimized". Those are two different things.

Therefore, my only advice for my past self and anyone who wants to get started with open source: get ready to learn. If you are interested in a project but clueless about how to get started, learn about it from the community (git grep or VSCode search tool may be your best buddy, but a supportive community is your wife/husband). If you don't know how to fix a particular bug, learn how others approach(ed) it. If you want others to help you out with your open source project, communicate with other maintainers and learn how they treat new contributors. In open source, I think we are all here to grow not only as a developer but as a community.

Conclusion

I wish open source could be applied to many other aspects in life. It's a bit embarrassing to admit how obsessed I am with open source. In fact, I was so used to filing a new issue on an open source project and requesting to work on it that I unconsciously did the same thing to Scotiabank the other day. The bank tellers must have thought I was high on drugs or something. Finally, I'd like to thank David, who helped other students and me fall into this fascinating rabbit hole. If you are reading this (which is very likely), we really appreciate your amazing content and support, Dave! That was an incredible adventure from Release 0.1 to 0.4 and the labs. I'm looking forward to the my next chapter after this course.

Cover photo by Lala Azizli on Unsplash

Wrapping Zulip's Issue Up

Oliver Pham — Sat, 11 Dec 2021 04:31:41 +0000

As I was preparing for my finals and fixing some automation tests for my Pull Request (PR), I realized I had made a serious mistake. I was clearly under no influence of alcohol, but I managed to write this comment:

Comment for #20494

oliver-pham commented on Dec 09, 2021

~~That's strange. The tests actually passed when I ran them locally. Should I try to fix it, @timabbott?~~ Sorry, I forgot to run the tests for the whole codebase.

Edited: ~~I have no idea how to approach this, so it might take some more days~~

Edited 2: I think I know why now. I removed the use of make_query_highlighter() in search_suggestion.js. It became obsolete since it was used there only. If I'm not mistaken, it was used to make every matching character of a suggestion bold. In this case, it's the full name of a user. Because the name is inside a pill now, I think the bold text doesn't stand out a lot like it used to. Should I add the feature back?

View on GitHub

What happened

I'd like give you some background information first. Zulip strives to maintain 100% code coverage. In order for my PR to be merged, it must meet that requirement. If the code coverage is compromised, this message will be displayed:

Believing that getting all my tests passed was enough, my PR failed the CI check at first. Unfortunately, that wasn't the worst part.

Thanks to the test coverage, I noticed there was an unused function. It was used by some functions that I'd modified. This was a huge red flag, but it took me some time to realize that I removed an existing feature without asking the maintainers 🤦. Specifically, the feature highlights any substring in a suggestion that matches their query.

In my defense, there was a complication with integrating the new feature (i.e. showing avatar and username in pill-shaped UI elements) with the one mentioned above. I quickly discussed the issue with the maintainers.

My first attempt at solving it failed. Forgetting the test my code thoroughly, I made a silly mistake by double-escaping HTML expressions in every user's name:

Comment for #20494

oliver-pham commented on Dec 10, 2021

Sure, @alya! Here you go:

https://user-images.githubusercontent.com/55090719/145640417-cf8a40cd-871d-47e4-83ff-b819bb17ac2d.mov

... and thanks to you, I found something that looks a bit off. Right now, ' is currently considered a dangerous character (replaced by HTML entity &#x27). Currently, it seems that we allow that character to be in a full name, so let me try to make a patch for it. Is there anything else I should change?

View on GitHub

Thankfully, I managed to patch my mistake instantly. Here's how it looks:

What I've learnt

Thanks to the test coverage report, I managed to discover my embarrassing flaw. Although it may be annoying to update the tests at times, I think I've learnt to appreciate a good CI pipeline setup more than ever. I found Zulip's docs a good resource for how a developer should approach testing.

I've also recognized the importance of sleep to keep my sanity. Looking back on my comments and code, I'm astonished by my audacity to have made such mistakes. I should have got started earlier to allow myself more time to get familiar with Zulip's codebase.

What's next

Since my PR is still under review by the time I'm writing this blog, I'll try to improve it until it's merged. There are not (hopefully) a lot of things left to do with it, so it should be done soon.

Cover photo by Brooke Cagle on Unsplash

My Progress on Zulip's Issue

Oliver Pham — Tue, 07 Dec 2021 20:23:30 +0000

In preparing for battle I have always found that plans are useless, but planning is indispensable. - Dwight D. Eisenhower

Indeed my initial approach to the issue wasn't a good one, but it was not useless. Discussing it with several Zulip members & contributors helped me come up with a neater one and complete a prototype. After some refinement, I finally made a pull request for the feature.

search_suggestion: Show profile pictures in search auto-complete suggestions #20494

oliver-pham posted on Dec 07, 2021

Fix #20267

What I've basically changed is how bootstrap-typeahead should render the auto-complete suggestions for users only. I've attempted to reuse the existing UI components (e.g. input_pill) and styling, but it seems hard to make them work together as expected without adding a container and some CSS. If you find a better approach, I'm open to all recommendations.

During the process of encapsulating the typeahead list items inside flexboxes, I noticed the whitespace right after prefix is not escaped in HTML. This can cause, for example, "StreamDenmark" because the whitespace before "Denmark", which is wrapped with <strong> tags, is ignored in HTML.

Testing plan:

Manual Testing

GIFs or screenshots: On large screens:

On smaller screens:

View on GitHub

What happened

A few hours after my messages were sent, I got some helpful feedback to my initial thoughts. Basically, I was advised to modify a more relevant, lower-level function, get_person_suggestions(). That should help me avoid breaking the existing features.

My first prototype for the feature looks like this:

It's really ugly, wasn't it? I was then advised to use an existing UI component, user_pill, to display a user's full name and avatar as a distinct block. Another refinement was to vertically align the text. I eventually implemented both, which significantly improved the design of my initial prototype.

What I've learnt

I should have made a draft/work-in-progress pull request early in my development process and improved on it iteratively. Keeping others posted of my prototype of the feature was a good idea, but I missed out another important deliverable: my nasty code. Working with an open source community means that I can get feedback for me code more easily, so I should've taken advantage of that.

What's next

Hopefully, the maintainers will review my code soon. In the meantime, I probably need to fix some broken automation tests.

Cover photo by Mohammad Rahmani on Unsplash

Initial Thoughts on a Zulip's Issue

Oliver Pham — Thu, 02 Dec 2021 03:48:37 +0000

At the beginning of this week, I've found an interesting issue on Zulip's repo.

zulip / zulip

Zulip server and web application. Open-source team chat that helps teams stay productive and focused.

Zulip overview

Zulip is an open-source team collaboration tool with unique topic-based threading that combines the best of email and chat to make remote work productive and delightful. Fortune 500 companies, leading open source projects, and thousands of other organizations use Zulip every day. Zulip is the only modern team chat app that is designed for both live and asynchronous conversations.

Zulip is built by a distributed community of developers from all around the world, with 74+ people who have each contributed 100+ commits. With over 1000 contributors merging over 500 commits a month, Zulip is the largest and fastest growing open source team chat project.

Come find us on the development community chat!

Getting started

Contributing code. Check out our guide for new contributors to get started. We have invested in making Zulip’s code highly readable, thoughtfully tested, and easy to modify. Beyond that, we have…

View on GitHub

Zulip is a popular open source communication platform built with Django (Python). Despite having spent some time one it, I eventually let another developer handle that issue¹ and claimed another one. It's a feature request for showing profile pictures in search autocomplete suggestions.

Show profile pictures in search auto-complete suggestions #20267

alya posted on Nov 16, 2021

At present, we show profile pictures in @-mention auto-complete suggestions, but not in auto-complete suggestions for search. As a result, it's hard to quickly find the person you need in search auto-complete. Moreover, using the search suggestions is very awkward when multiple people have the same name.

To address this, we should show avatars in the search auto-complete suggestions when a user is being suggested (sender, PMs with, etc.).

From an implementation perspective, we would ideally reuse the send-PM-pills component rather than duplicating the logic.

CZO discussion thread

For reference, the @-mention UI:

Current search suggestions UI:

View on GitHub

What the feature involves

I was overwhelmed with Zulip's gigantic codebase and technologies. Luckily, their documentation is really clear, concise, and helpful. Although setting up a local development environment for the project took more time than usual, the process was straightforward. I had a chance to learn a bit about Docker and Vagrant. Apart from that, I had an unexpected reunion with Git's pre-commit hooks, my old friend from OSD's lab.

The next part was a nightmare: tracing the relevant code in a codebase developed by 700+ contributors with 45000+ commits. After doing some research and receiving support from Zulip's community server, I've had some ideas for the feature.

Based on an existing approach to a relatively similar feature, I need to customize the existing typeahead.js's layout to include an avatar for any suggested person or organization. As the author of the issue suggested, I could reuse a Handlebars partial for each suggestion.

How I approach it

Firstly, I need a way to render a user's profile picture from their name. After some code tracing, I found render_person_or_user_group(), a typeahead's helper function that can help me with that task. It uses this Handlebars partial to render a suggestion:

{{#if is_emoji}}
    {{#if has_image}}
        <img class="emoji" src="{{ img_src }}" />
    {{else}}
        <span class='emoji emoji-{{ emoji_code }}'></span>
    {{/if}}
    &nbsp;&nbsp;
{{else}}
    {{#if is_person}}
        {{#if user_circle_class}}
        <span class="{{user_circle_class}} user_circle"></span>
        {{/if}}
        {{#if has_image}}
        <img class="typeahead-image" src="{{ img_src }}" />
        {{else}}
        <span class='typeahead-image fa fa-bullhorn no-presence-circle'></span>
        {{/if}}
    {{else}}
        {{#if is_user_group}}
        <i class="typeahead-image icon fa fa-group no-presence-circle" aria-hidden="true"></i>
        {{/if}}
    {{/if}}
{{/if}}
<strong>
    {{~ primary ~}}
</strong>
{{~#if has_secondary}}
&nbsp;&nbsp;
<small class="autocomplete_secondary">
    {{~ secondary ~}}
</small>
{{#if is_unsubscribed}}
&nbsp;
<span class="fa fa-exclamation-triangle unsubscribed_icon"
  title="{{t 'You are not currently subscribed to this stream.' }}"></span>
{{/if}}
{{~/if}}

Having said that, I still need more time to understand the behaviour of the function. It's likely that I have to write a similar one to exclude the irrelevant.

Secondly, I need to find a way to customize a suggestion's layout. After some research, I noticed highlighter() is responsible for it:

highlighter(item) {
   const obj = search_map.get(item);
   return obj.description;
}

obj.description is some bizarre raw HTML with a par of <strong> tags, enclosing each character of a name, and another one that follows it and encloses absolutely nothing. For instance, the HTML for "Sent by Aayush Solanki" looks like this:

<a href="#">Sent by <strong>A</strong><strong></strong><strong>a</strong><strong></strong><strong>y</strong><strong></strong><strong>u</strong><strong></strong><strong>s</strong><strong></strong><strong>h</strong> <strong>S</strong><strong></strong><strong>o</strong><strong></strong><strong>l</strong><strong></strong><strong>a</strong><strong></strong><strong>n</strong><strong></strong><strong>k</strong><strong></strong><strong>i</strong></a>

Finally, I must come up with a way to connect the two functions seamlessly. This is the most complicated part.

Conclusion

This seems like an impactful contribution to a large open source project. I'm still clueless about how to build upon my initial approach, but I'll try to keep you posted about my progress.

Cover photo by Kaleidico on Unsplash

There was another developer who had worked on the issue before me. He abandoned the issue due to his college work. However, he asked to work on it again a day after I discussed my approaches with the project maintainers. Since he claimed to have some progress on it already, I decided to let him take over the issue. Do you think I've done the right thing in this situation? Let me know the comments. ↩

Publish a Python Project in 5 Steps

Oliver Pham — Sat, 27 Nov 2021 03:10:01 +0000

This week, I've published Silkie, my Python static site generator (SSG), to PyPI. It may seem daunting at first, but you can publish your own Python package by following these 5 steps.

Start

To avoid most painful misconfiguration, I organized my project to follow a standard directory structure:

silkie
├── LICENSE
├── README.md
├── pyproject.toml
├── requirements.txt
├── setup.cfg
├── silkie
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py
│   ├── ...
├── tests
└── tox.ini

You might want to use Cookiecutter to set up a template for your Python project if you are starting from scratch.

We'll be uploading our package to PyPI, so we should have an account created on PyPI. In addition, you can also create another account on TestPyPI to test your package first before an official publication.

Configure

Setuptools, a popular and extensible library for packaging Python projects, seems like a perfect choice for my project. Configuration steps for it includes writing two files: pyproject.toml and setup.cfg.

The pyproject.toml file simply declares the requirements for building our package:

[build-system]
requires = [
    "setuptools>=42",
    "wheel"
]
build-backend = "setuptools.build_meta"

Based on your project architecture, setup.cfg can be configured accordingly. I think this tutorial does a better job explaining the details, so you should definitely check it out. As for Silkie, this is how I set it up:

[metadata]
name = silkie
version = 1.0.7
...
description = Static site generator with the smoothness of silk
long_description = file: README.md
long_description_content_type = text/markdown
url = https://github.com/oliver-pham/silkie
project_urls =
    Bug Tracker = https://github.com/oliver-pham/silkie/issues
classifiers =
    Programming Language :: Python :: 3
    License :: OSI Approved :: MIT License
    Operating System :: OS Independent

[options]
packages = silkie
python_requires = >=3.9
install_requires =
    click >= 8.0.0
    markdown >= 3.3.0
    yattag >= 1.14.0
    python-frontmatter >= 1.0.0

[options.entry_points]
console_scripts = 
    silkie = silkie.cli:silkie

Some notes you may want to consider to avoid some misconfigurations (that I made):

packages: I specify silkie directory directly because my project only has a single package. If you have multiple packages nested under a single directory, you should use find: and follow the instructions in Setuptools documentation
install_requires: specify all third-party dependencies that your project use. Simply put, anything that you pip install and import in your code should be declared here

Build

Once you are done with configuration, let's build your Python package.

Before we can build it, make sure you have the latest version of build installed on your machine.

$ pip install --upgrade build

Then, just run build in the root directory of your project:

$ python -m build

You should have a .whl file and a .tar.gz file inside your dist/ directory when the build process is completed.

Test

Before publishing your package, make sure that the newly built distribution contains all the necessary packages and files. You can run this command to see what's inside your distribution:

$ tar tzf <your-package-name>.tar.gz

Publish

To publish your Python package to PyPI, you must have twine installed on your machine. You can install its latest version with pip:

$ pip install --upgrade twine

Once it's installed, run this command to upload your distribution to TestPyPI for testing:

$ twine upload --repository TestPyPI dist/*

When prompted, you can either enter your account credentials or use an API token like this:

Enter your username: __token__
Enter your password: <your-API-token>

When your package can be uploaded to TestPyPI and installed on your local machine, you're ready to upload it to PyPI:

$ twine upload dist/*

Just like TestPyPI, your credentials or API token (for PyPI) can be used to authenticate your upload. Congratulations! You can now ask others to install and test your package.

As for Silkie, I've asked some of my friends to test the SSG. One of them found a critical bug due to a lack of testing. Another one suggested a piece of ASCII Art to me for Silkie, which was really nice. Overall, we have only tested it on Mac and Linux. If you happen to encounter any bug or issue while using Silkie, feel free to open an issue on GitHub.

Final thoughts

In general, I think publishing a Python package isn't really complex, but I was so nervous that I made a lot mistakes. It's fine if you mess up your release because you can always apply a new patch to it (unless your package is used by a majority of developers). Happy coding!

How I Set Up GitHub Actions for a Python Project

Oliver Pham — Sat, 20 Nov 2021 17:24:10 +0000

Last week, I already set up some automation tests for Silkie, my static site generator (SSG). Instead of running tests manually on each Pull Request (PR), I made an attempt to configure GitHub Actions to automate this Continuous Integration (CI) workflow. Moreover, I also helped my friend, Luke, add a test case to his SSG this week.

Configure GitHub Actions

For the time being, I have several specifications for my CI pipeline:

Test Silke only on Python 3.9 (hopefully I can support more versions in future releases)
Install dependencies from requirements.txt file (if it exists)
Run Flake8 linter
Run tests and generate code coverage

Here's how it actually looks like:

# This is a basic workflow to help you get started with Actions

name: CI

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the main branch
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.9"]

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v2

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v2
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
      - name: Run flake8 linter
        run: |
          pip install flake8
          # stop the build if there are Python syntax errors or undefined names
          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
          # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
      - name: Test & Code coverage with pytest
        run: |
          pip install pytest
          pip install pytest-cov
          pytest --junitxml=junit/test-results.xml --cov=silkie --cov-report=xml --cov-report=html

Testing Luke's SSG

Luke used Jest as his testing framework. In my opinion, it wasn't really different from Pytest, so I had no problem with adding a new test case.

Luke had also set up a simple but efficient CI workflow for his project:

# This workflow will do a clean install of node dependencies, cache/restore them, build the source code and run tests across different versions of node
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions

name: Node.js CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [14.x, 16.x]
        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/

    steps:
      - uses: actions/checkout@v2
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

Luckily, my newly added test case didn't fail the CI workflow, so my PR got merged eventually.

Final thoughts

I think it's pretty easy and simple to get a CI pipeline up and running with GitHub Actions. However, its impact on our productivity and code quality is certainly significant as the project grows bigger.

How I Fixed an Issue in Firebase CLI

Oliver Pham — Sat, 20 Nov 2021 04:00:31 +0000

I found an issue on Firebase CLI repo that I could work on. The issue involved a hardcoded Node.js version in the generated package.json file when the command firebase init functions is executed. Moreover, there was no warning when a Node.js version in use is deprecated in Google Cloud Functions.

Getting started

To be honest, I had no idea how to approach this issue at first, so I decided to follow the contributing guide. It was very detailed and straightforward, so I had no problem setting up firebase-tools. Unlike the previous open source projects, I had to sign Google's Contributor License Agreement (CLA) before I could contribute to Firebase CLI. Thanks to the intuitive folder structure of the project, I could identify which files to be modified.

Dynamically set Node version

Based on the folder structure, firebase init functions should execute the code inside firebase-tools/src/init/features/functions/<language>.js (<language> is the programming language selected for your project). I made a comment on the issue to discuss my approach. Thankfully, I got some super helpful recommendations from Daniel, the author of the issue.

Basically, the package.json file is generated from a pre-written template. To set the right Node.js version, I needed the logic to identify it and replace the hardcoded version with it dynamically.

First, I replaced the hardcoded version with a template string inside package.json template file:

  "engines": {
    "node": "{{NODE_VERSION}}"
  },

Then, a reliable function to detect Node.js version was implemented:

export function getNodeVersionString(): string {
  return process.versions.node.split(".")[0];
}

Lastly, before writing package.json file to a dev's machine, I just need to replace the template string with the detected Node.js version like this:

const nodeEngineVersion = getNodeVersionString();
if (useLint) {
    return PACKAGE_LINTING_TEMPLATE.replace(/{{NODE_VERSION}}/g, nodeEngineVersion);
  }
return PACKAGE_NO_LINTING_TEMPLATE.replace(/{{NODE_VERSION}}/g, nodeEngineVersion);

PACKAGE_LINTING_TEMPLATE: the content of package.json file with ESLint
PACKAGE_NO_LINTING_TEMPLATE: the content of package.json file without ESLint

Handle deprecated Node versions

The logic to warn developers of deprecated Node.js versions was still missing, so I discussed my approach with Daniel again. I intended to use a function that I found in their codebase, isDeprecatedRuntime(), to perform the check.

Luckily, Daniel pointed out a small bug in my approach and suggested a better one, which was to use isValidRuntime() instead. I finally got the last piece as:

if (!isValidRuntime(`nodejs${nodeEngineVersion}`)) {
    utils.logWarning(`Node ${nodeEngineVersion} is no longer supported in Google Cloud Functions.`);
    utils.logWarning(
      "See https://firebase.google.com/docs/functions/manage-functions for more details"
    );
}

Final thoughts

I've never had to fix my code for a PR as much as this one. Thanks to their code review, I've learned a few good practices along with how I could avoid pitfalls by discussing my approach and getting feedback before actually coding it.

Issue: https://github.com/firebase/firebase-tools/issues/3407
PR: https://github.com/firebase/firebase-tools/pull/3894
Firebase: https://firebase.google.com

How I Reviewed Code for Seneca-ICTOER

Oliver Pham — Sat, 20 Nov 2021 04:00:18 +0000

As I was working on the modernized version of IPC144, there were many pending pull requests (PR) made by other students. I decided to help them out with reviewing their pull requests. Most of them were well done, so I could only give a few recommendations to some of them. Here are two of them.

Reviewed PR for `Informataion.md`

In the PR, I noticed the author accidentally committed two irrelevant files: https-webhint-io.html and yarn.lock. He was supposed to modify only a Markdown file, but he probably added his Web Hint's report by mistake. I made a comment on it, which helped him eventually remove those irrelevant files from his PR.

Reviewed PR for `More Input and Output.md`

After reviewing the PR, I noticed a tiny whitespace character that could lead to misunderstanding. The original text was:

"%*c%c" discards/ignores one character and accepts the next.
" %c" discards/ignores all whitespace characters before the next non-whitespace character.

The whitespace in " %c" was then removed by the author. However, this whitespace character was actually necessary for the expression to discard/ignore all whitespace characters.

Final thoughts

Code review surely requires attention to details, but it can be done more easily with collaboration. I really appreciate others' effort on reviewing my PR and suggesting interesting areas of improvement. I hope that I have a chance to review more challenging work next time.

PR #1: https://github.com/Seneca-ICTOER/IPC144/pull/81
PR #2: https://github.com/Seneca-ICTOER/IPC144/pull/84

How I Contributed to an OER Project

Oliver Pham — Sat, 20 Nov 2021 04:00:06 +0000

I finally had a chance to work on IPC144, an Open Educational Resources (OER) project with a view to modernizing the old IPC144 course website with Docusaurus. As a first time contributor, I found a perfect issue to get familiar with the project: auditing and fixing the automatically translated Markdown files.

Getting started

As instructed in the meta issue, I opened a new issue for the page on which I'd like to work. Once I'd cloned the repository, I could immediately start auditing the Markdown file without any additional configuration. I had to go over a long checklist posted in the meta issue, but I'll discuss what I've found interesting in this blog.

Docusaurus Features

Docusaurus has 2 distinct features that can significantly improve the old IPC144 website:

Frontmatter: the top section of a content file used for specifying metadata and Docusaurus's configuration variables
Admonition: a highlighted section in a content file

Frontmatter

Docusaurus supports a large number of Frontmatter fields. I added 4 of them to the Markdown file for SEO optimization:

---
id: algorithms
...
title: "Algorithms"
slug: /refinements/algorithms
description: "An algorithm is the set of rules that define the sequence of operations required to complete the task."
---

Admonition

There were some noteworthy sections of the page. However, they barely stood out because of the use of Markdown blockquote like this:

Luckily, Docusaurus' Admonition is perfect for this role. It is really eye-catching and easy to use. For example, I can enclose the content with :::note and ::::

:::note

The value returned by `find()` (variable `i`) is validated to ensure that it is within the bounds of the key array (that is, we check that it is not -1 and not more than the number of items in the array). 

:::

and it will be rendered like this:

Final thoughts

Although it might seem like a small issue, it's still very satisfying to know that my contribution can enhance the learning experience of other fellow students.

Issue: https://github.com/Seneca-ICTOER/IPC144/issues/28
PR: https://github.com/Seneca-ICTOER/IPC144/pull/72
Docusaurus: https://docusaurus.io/docs

How I Set Up Testing for My Python Project

Oliver Pham — Fri, 12 Nov 2021 20:56:20 +0000

After setting up static analysis tools last week, it's time to configure a testing framework for Continuous Integration (CI). There are several options for Silkie, my work-in-progress static site generator, but I decided to give Pytest a try. In this blog, I'll show you how I set up:

pytest - a Python testing framework
pytest-watch - a CLI tool for running tests automatically on changes
pytest-cov - a Pytest's plugin for producing code coverage reports

Pytest

I find Pytest easy to set up tests without too much boilerplate code and to add more functionalities with many extensions. You can add it to your project with a single installation command:

$ pip install -U pytest

You can check whether it's already installed with:

$ pytest --version

You can write your test as easy as adding a Python function. First, create a file whose name starts with test_ or ends with _test. Pytest automatically discovers those tests if you name them according to their convention. In my case, I created test_get_file_name.py for testing this function:

def get_filename(file_path: str) -> str:
    """Extract the name of the file from a file path and exclude any file extension"""
    return Path(file_path).stem.split(".")[0]

Then, simply add your test cases as Python functions. For instance, I tried to test whether my get_filename() function works on a file path of both Windows and Unix. I also wanted to check if it can exclude multiple file extensions from the file name:

def test_windows_file_path():
    expected_file_name = "test"
    file_extension = "txt"
    file_path = fr"C:\Documents\{expected_file_name}.{file_extension}"
    file_name = get_filename(file_path=file_path)

    assert file_name == expected_file_name


def test_unix_file_path():
    expected_file_name = "test"
    file_extension = "txt"
    file_path = f"/Users/anonymous/Documents/{expected_file_name}.{file_extension}"
    file_name = get_filename(file_path=file_path)

    assert file_name == expected_file_name


def test_file_path_multiple_extensions():
    expected_file_name = "test"
    file_extension = "rc.txt"
    file_path = f"/Users/anonymous/Documents/{expected_file_name}.{file_extension}"
    file_name = get_filename(file_path=file_path)

    assert file_name == expected_file_name

I also configured Pytest to only search for tests in my tests folder by specifying it in pytest.ini file:

[pytest]
minversion = 6.0
testpaths = tests

Then, I can finally run my tests with this command:

$ pytest

Unexpectedly, I caught an error in my code. The test failed when a Windows file path is passed to the function:

====================================================================================================== test session starts =======================================================================================================
platform darwin -- Python 3.9.7, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
rootdir: /Users/ptpham/Projects/silkie
collected 3 items                                                                                                                                                                                                                

tests/unit/test_get_file_name.py F..                                                                                                                                                                                       [100%]

============================================================================================================ FAILURES ============================================================================================================
_____________________________________________________________________________________________________ test_windows_file_path _____________________________________________________________________________________________________

    def test_windows_file_path():
        expected_file_name = "test"
        file_extension = "txt"
        file_path = fr"C:\Documents\{expected_file_name}.{file_extension}"
        file_name = get_filename(file_path=file_path)

>       assert file_name == expected_file_name
E       AssertionError: assert 'C:\\Documents\\test' == 'test'
E         - test
E         + C:\Documents\test

tests/unit/test_get_file_name.py:10: AssertionError
==================================================================================================== short test summary info =====================================================================================================
FAILED tests/unit/test_get_file_name.py::test_windows_file_path - AssertionError: assert 'C:\\Documents\\test' == 'test'
================================================================================================== 1 failed, 2 passed in 0.19s ===================================================================================================

I decided to apply a quick fix to the function:

def get_filename(file_path: str) -> str:
    """Extract the name of the file from a file path and exclude any file extension"""
    ...
    # Replace any backslash(es) in Windows file path with forwardslash(es)
    file_path = file_path.replace("\\", "/")
    return Path(file_path).stem.split(".")[0]

It made the test passed 🥳! With pytest working, let's set up pytest-watch so my tests can run automatically whenever I make some changes to my source code.

Pytest-watch

pytest-watch is a zero-config CLI tool that runs pytest, and re-runs it when a file in your project changes

If you don't want to run your tests manually every time you update your code, you can install this tool with this command:

$ pip install pytest-watch

Then, you just need to run the tool in the root directory:

$ ptw

Pytest-cov

pytest-cov is a pytest's plugin that produces coverage reports. If you want to see how much your tests have covered your codebase, you can install this tool by running this command:

$ pip install pytest-cov

Once the package is installed, you can run pytest-cov by adding --cov=<your-root-folder> to your pytest command. In my case, I'd also like to see which lines of code are not covered by running this command:

$ pytest --cov-report term-missing  --cov=silkie

Conclusion

Setting up a testing framework isn't as complicated as I expected, but it's certainly beneficial to my project's quality.

2 Static Analysis Tools to Enhance Your Productivity

Oliver Pham — Sat, 06 Nov 2021 03:01:57 +0000

If you are tired of maintaining your coding style, I have good news for you. Fortunately, there are developer tools that can automate and streamline mundane development tasks. In this blog, I'll show you how I integrated 2 static code analysis tools and a package manager for pre-commit hooks into Silke, my work-in-progress static site generator.

Black: The uncompromising Python code formatter

Black can help you automatically format your Python code that follows (most of) the style conventions in PEP 8. You can install this tool with Pip and Python 3.6.2+:

$ pip install black

After installation, Black should work without configuring anything else:

$ black .

Once Black is executed, it will tell you which files have been reformatted. When I ran it on Silkie, Black produced the following output:

reformatted silkie/silkie.py
All done! ✨ 🍰 ✨
1 file reformatted.

After testing Silkie, I was pleasantly amazed that Black didn't break my code. If you are still worried that Black may break your program by alternating your code, you can include the --diff flag when running it. That should allow Black to only suggest their changes.

VSCode Integration

If you use Visual Studio Code as your code editor, you can easily integrate Black into it. First, you need to create a settings.json file under .vscode folder if you haven't had it. Then, add these 2 lines to enable Black to reformat your Python code when you save your files:

{
    "python.formatting.provider": "black",
    "editor.formatOnSave": true,
}

Flake8: Python 3-in-one linter

A code linter should help developers identify potential errors and coding style violations in your code; and I think Flake8 can accomplish that. Flake8 combines PyFlakes, pycodestyle, and Ned Batchelder's McCabe script to enhance our Python code quality.

Setting it up is as easy as a one-line command:

pip install flake8

Once it's installed, you can run it on your project right away. However, you can save your time later by specifying which files and/or directories Flake8 should exclude from its scan. In order to do that:

Create a tox.ini file in your root directory.
Specify the excluded files/folders separated by commas. Take my project as an example:

[flake8]
exclude =
    # Version control directory
    .git,
    # GitHub configuration directory
    .github
    # Python compiled bytecode 
    __pycache__,
    # Python third-party libraries & packages
    lib,
    # Python scripts & binary files
    bin,
    # Build directory
    dist,

Then, I ran Flake8 on my project:

$ flake8 .

By default, Flake8's style rules may have some conflicts with Black's. For instance, although Black already formatted my code, Flake8 would still bug me for having too many characters per line:

./silkie/silkie.py:37:80: E501 line too long (83 > 79 characters)
./silkie/silkie.py:43:80: E501 line too long (84 > 79 characters)
./silkie/silkie.py:52:80: E501 line too long (80 > 79 characters)
./silkie/silkie.py:76:80: E501 line too long (86 > 79 characters)
./silkie/silkie.py:80:80: E501 line too long (80 > 79 characters)
./silkie/silkie.py:104:80: E501 line too long (80 > 79 characters)
./silkie/silkie.py:149:80: E501 line too long (80 > 79 characters)
./silkie/silkie.py:157:80: E501 line too long (80 > 79 characters)
./silkie/silkie.py:159:80: E501 line too long (83 > 79 characters)
./silkie/silkie.py:199:80: E501 line too long (85 > 79 characters)
./silkie/silkie.py:210:80: E501 line too long (88 > 79 characters)

Moreover, Flake8 found a false positive error:

./silkie/silkie.py:159:56: E203 whitespace before ':'

Flake8 actually complained about the whitespace before a list slice:

To resolve those issues, I configured Flake8 in tox.ini file, located in the root directory, to ignore those false positive stylistic errors:

[flake8]
max-line-length = 88
ignore =
    # False positive whitespace before ':' on list slice.
    # See https://github.com/PyCQA/pycodestyle/issues/373 for details
    E203

VSCode Integration

Flake8 can integrated into Visual Studio Code by adding these lines to settings.json file under .vscode folder:

{
    "python.linting.flake8Enabled": true,
    "python.linting.enabled": true,
    "python.linting.flake8Args": ["--max-line-length=88"],
    ...
}

Pre-commit: Multi-language pre-commit hooks manager

If you don't want to manually run Black and Flake8 before committing your changes, you can automate it with pre-commit.

To install pre-commit, run this command:

$ pip install pre-commit

Once it's installed, you can set up pre-commit hooks by specifying them in the .pre-commit-config.yaml file. For example, this is how I added Black and Flake8 as pre-commit Git hook scripts to my project:

repos:
  - repo: https://github.com/psf/black
    rev: 21.10b0
    hooks:
      - id: black
  - repo: https://github.com/pycqa/flake8
    rev: 4.0.1
    hooks:
      - id: flake8

To run these tools before every git commit commands, you need to install the scripts with this command:

$ pre-commit install

After installation, Black and Flake8 should be executed before any modification is committed.

Conclusion

I initially thought integrating these tools into my project would take a lot of time, but it was actually really quick and straightforward. Thanks to the development teams behind Black & Flake8, my life as a developer has been much easier. I can't wait to try out other awesome tools!

3 Ways to Get Unstuck while Fixing Bugs

Oliver Pham — Sun, 31 Oct 2021 03:27:08 +0000

When you contribute to open source projects, getting frustrated with arbitrary issues is inevitable. I was in the same situation while trying to resolve an issue about writing a demo cloud function for one of Appwrite's features. There were 3 resources that helped me get through the problems:

Documentation
Community Channels
GitHub Issues

Context

Let's take a look at the issue for an overall context:

Your task is to implement generateOpenStreetMap function. You can look at the existing Appwrite Functions demo in the coding language you prefer to see how it works.

This function should take latitude and longitude as an input, generate map preview using OpenStreetMap API and save it into Appwrite Storage.

There were 3 main challenges I had to tackle:

Creating an Appwrite Cloud Function (I can somewhat understand the process)
Write my code in Ruby (doesn't look really bad)
Implementing OpenStreetMap API (absolutely clueless)

📜 Documentation

While experimenting with a new technology, you should seek out its documentation first. You can find the answers to most of your questions there. If you try asking for help before reading the docs, you'll probably get this kind of response:

Well, not really that rude, but they will tell you to read it first most of the time. In my case, thanks to their docs, I could easily create an Appwrite Function for Ruby. The process was pretty straightforward, so instead of discussing it with someone else, I just tested it myself.

On the other hand, documentation can sometimes be outdated or too hard to navigate to the part that you need. In fact, OpenStreetMap Wiki took me quite a lot time to find out how I could retrieve a map image from their API. Because even the search box can't find any explicit example of such functionality, I struggled for a few days until I decided to reach out to the next source of support: community channels.

💬 Community Channels

Almost every open source projects that welcome contributors use a platform for communication (e.g. Discord, Slack, and Matrix). This should help you resolve most issues which can't be found in the docs.

Just kidding. Most of the time, you'll get more helpful advice. For example, I realized my initial approach to get a map image from OpenStreetMap API was a dead end after discussing it with a project member on Appwrite's Discord server. Thankfully, I was introduced to OpenStreetMap tile server, where I can get a static map image from a tile number. Moreover, I even found the exact code snippet from the docs for calculating the tile number from a latitude, a longitude, and a zoom level:

# Source: https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames#Ruby
def get_tile_number(lat_deg, lng_deg, zoom)
  lat_rad = lat_deg/180 * Math::PI
  n = 2.0 ** zoom
  x = ((lng_deg + 180.0) / 360.0 * n).to_i
  y = ((1.0 - Math::log(Math::tan(lat_rad) + (1 / Math::cos(lat_rad))) / Math::PI) / 2.0 * n).to_i

  {:x => x, :y =>y}
end

🎫 GitHub Issues

Sometimes, when something doesn't work as expected, it's not your fault. It can be a bug that has yet to be detected. Even if it is not, you will get more attention to your issue when you file it on GitHub.

While testing my cloud function on Appwrite Console, I got a bizzare error with my HTTP requests. After doing a lot of research online and asking for help on Discord, I still had no clue. When I was about to give up, I decided to file an issue on Appwrite's repo saying how my function didn't work as expected. After a while, I got a response.

After following his suggestion, I managed to fix the bug and eventually made a pull request. You can check out my recent blog post to learn more details about how I implemented and deployed the cloud function.

This is my last blog post for Hacktoberfest 2021. It was truly an amazing and eye-opening journey! I'm really looking forward to participating in Hacktoberfest again next year.

DEV Community: Oliver Pham

How My View on Open Source Has Changed

Supportive Community

Amazing opportunity to learn

What Open Source really is

Conclusion

Wrapping Zulip's Issue Up

Comment for #20494

What happened

Comment for #20494

What I've learnt

What's next

My Progress on Zulip's Issue

search_suggestion: Show profile pictures in search auto-complete suggestions #20494

What happened

What I've learnt

What's next

Initial Thoughts on a Zulip's Issue

zulip / zulip

Zulip server and web application. Open-source team chat that helps teams stay productive and focused.

Zulip overview

Getting started

Show profile pictures in search auto-complete suggestions #20267

What the feature involves

How I approach it

Conclusion

Publish a Python Project in 5 Steps

Start

Configure

Build

Test

Publish

Final thoughts

How I Set Up GitHub Actions for a Python Project

Configure GitHub Actions

Testing Luke's SSG

Final thoughts

How I Fixed an Issue in Firebase CLI

Getting started

Dynamically set Node version

Handle deprecated Node versions

Final thoughts

How I Reviewed Code for Seneca-ICTOER

Reviewed PR for Informataion.md

Reviewed PR for More Input and Output.md

Final thoughts

How I Contributed to an OER Project

Getting started

Docusaurus Features

Frontmatter

Admonition

Final thoughts

How I Set Up Testing for My Python Project

Pytest

Pytest-watch

Pytest-cov

Conclusion

2 Static Analysis Tools to Enhance Your Productivity

Black: The uncompromising Python code formatter

VSCode Integration

Flake8: Python 3-in-one linter

VSCode Integration

Pre-commit: Multi-language pre-commit hooks manager

Conclusion

3 Ways to Get Unstuck while Fixing Bugs

Context

📜 Documentation

💬 Community Channels

🎫 GitHub Issues

Reviewed PR for `Informataion.md`

Reviewed PR for `More Input and Output.md`