DEV Community: Yuan-Hsi Lee

My last telescope post as a student (hopefully)

Yuan-Hsi Lee — Sat, 24 Apr 2021 04:46:32 +0000

This week, I still work with user accessibility. The footer has 2 corners that didn't meet the AA/AAA level of WCAG, contributor card, search result message, and slack icon. I want to talk about the slack icon one.

The slack icon we had was a svg file included in the project. We implemented it as a <img> like this,

<img src={slackLogo} alt="logo" height="20" width="20" />

What I needed to do is to change the color filling of this icon. This can be done by changing the fill value of svg element. The solution I wanted to try is to make this svg file as a react component so that I can configure the fill value. However, I wasn't able to import the svg file in typescript. I ended up using the easier way which is using react-icon and find the similar slack icon so that the filling color can be configured. I'd love to try more with the making svg a react component next time with SVGR.

It's been 4 months working with telescope team, and I'm very grateful with the chance of working with a group of amazing people.

Thanks to Dave for the astonishing lectures and leading, I'm so lucky to have your courses and to learn from you in my last year of college. Working in web development is totally unexpected to me, but you're one of the people who make me enjoy this field more than yesterday.

Thanks to Anton who helped me with git and your blog posts are always informative! Thanks to Chris, Royce, Abdul, Ilya, Tony, Huy, and Mo. It's a bit of overwhelming to work with a team that all people are more experienced and smarter than me, but it is lucky that I get to learn from you.

Thanks to Pedro, you're the first person who talked to me in the team and have always been supportive and kind to me!

I'm not good at saying good-bye, so I'm no gonna. But I want to tell everyone in the project that I truly appreciate everything you've done. It was amazing working with you all, wish you all the best :) ū-iân tsài siong-huē! (Meaning: We'll meet up again when the timing is right.) (This is Taiwanese, my mother language)

Keep working on accessibility

Yuan-Hsi Lee — Sun, 18 Apr 2021 19:00:46 +0000

Keep working with user accessibility this week. A simple change on our search help, the old font color is hard to read with the background color. I also make the title of the search help bolder and have some padding to make it more like a title.

Meanwhile, Royce is working with improve search help logic. The search help was only appeared before the user search anything. However, when the user can't find any result after the searching, it is possible that she could use some search help to get the wanted searching result. I believe this change of search help makes more sense and can be more helpful for the user.

When I was testing this PR, I found another issue related to user accessibility. (I thought I've been checking all corners already) There is a line of message telling the user "No results found" or "No more posts". This line of message in the search page has black color in both light and dark mode. Therefore, this line can't be seen in dark mode.

The issues that I've been working but not able to finish is to improve contrast ratio of slack icon. This slack icon is a svg file that we include in our repo. The color is white, and I'm not able to convert or fill in a darker color into it. This is my first time working with svg, the team gave me some suggestions in the weekly meeting, I will try to find out a fine solution to it!

First Attempt at Intersection Observer

Yuan-Hsi Lee — Mon, 12 Apr 2021 01:15:16 +0000

Thanks to Pedro, I learned a cool API this week and applied it in our favorite project telescope.

I was assigned an issue to accomplish the new banner design, which is to make the navbar appear only when the user scroll to the timeline. In other word, the navbar should not be showed in the banner, but, it should be showed when the first post is at the top of the screen.

To accomplish this feature, I need to track the element in the current screen. The API that Pedro introduced to me is Intersection Observer. The basic idea of this API is to observe the element in the viewport. The function isIntersecting() tells you if the element that you're observing is still in the viewport. It doesn't have to 100% in the screen or 100% out of the screen, the observed percentage can be configured as well.

Therefore, since our goal is to show the navbar when the user scrolls to the timeline, and the first post is at the top of the screen. In other word, the navbar should be showed when the banner is totally gone. We put the observer to our banner.

In this PR, I move <navbar> into <main>, so that I can separate it from the <Banner>. Moreover, to add props for <Banner> and <navbar> in order to share the result of intersection observer. After moving the position of navbar, I also need to add navbar to about page and search page, because all pages used to share the navbar when it was in the banner header. The other changes that needed to make is the CSS styling of navbar in about page. In about page, <a> uses a certain color from our palettes. Once we move navbar to about page, the navbar will be applied with these color because navbar icons all have <a> in their links. By adding another styling setting to <svg>, the color can be overridden. I'm still thinking if there is a better way to do so, since the original styling for navbar should not be overridden, and the solution should not be overridden to correct.

It was an amazing experience to work with something new. Thanks to Pedro and Dave's help and suggestion in this PR! The initial thought was actually using React context. However, it is too complicated to use, and since we only need to share the state with one component, we can do it without using context. But, I'm definitely gonna check out more practices of React context.

Prepare for telescope 2.0

Yuan-Hsi Lee — Tue, 06 Apr 2021 04:10:59 +0000

This week, I've been working mostly with UI changes, including user accessibility and investigating an issue in landing page for UI 2.0.

User accessibility

Use accessibility is one thing that I want to focus on telescope 2.0 release. There are many rules to follow to improve our user accessibility, and I started with the obvious one, which is checking the color contrast and size of all our pages and components. I've found the links color in dark mode, contribution card in dark mode, search help, slack icon can be improved. Also, since I'm working with mostly color styling, I also start to update the colors in our dark and light mode palette for better management.

Royce will be working with me on user accessibility, looking forward to working with him!

Landing page for UI 2.0

In Pedro's UI 2.0 project, he also plans to modify our banner. I'm assigned the part of moving nav bar from banner to timeline. The goal is to remove the nav bar from the banner, but show the nav bar when the user scrolls to timeline (posts). I've considered different solutions so far,

Move nav bar to timeline (posts) component
Currently, nav bar is above <main> so that we can always see it in the top-right corner of the page.
Only display nav bar when the timeline component touches the top of the screen
This one is challenging for me. I haven't worked with element positions with screen before, not sure how much time do I need to investigate it.
Make the nav bar component invisible in banner
If we don't want it to be showed on the banner area, why don't we make it invisible in that area? For example, make the navbar element "under" the banner element?

Developer experience

As mentioned in previous post(s), I've been updating documents to follow the changes in telescope (mostly microservice). I closed my old PR for adding a new, temporary document for microservice transition. Instead, I go back to existing documents, and update them. Start with environment-setup.md, I believe there are lots of documents can be updated.

User Accessibility and Developer Experience

Yuan-Hsi Lee — Sun, 28 Mar 2021 03:36:24 +0000

Telescope 1.9 release is shipped! Hooray!

In this week, I gain some new experience in user experience and developer experience. I'll explain them in this post.

UX

As discussed in the last post, Pedro and I want to handle the title issue. The old title has big font size which causes the title wrapped easily, and will need to expand the title to 2 lines, which is what we want to avoid.

In this PR, I shrunk the title size to make titles showed in one line (in most cases), and with smaller space used.

Before:

After:

This PR also solved the letter-spacing issue on mobile

Before:

After:

The other 2 PRs I want to mention is to improve user accessibility. We have an amazing dark mode to switch, but some font/element colors does not meet WCAG AAA rating, or even AA level.

Our old color choosing for links in dark mode looks like this,

The gray one is visited link and the light blue one is unvisited link. The gray one is hard to read, but when I check the contrast ratio, the blue one also has AA rating instead of AAA.

There are many colors I can choose to meet the required contrast ratio. However, I want it to be more consistent with light mode (the default mode). In light mode, unvisited link has blue color, and visited link has the color like dark red-violet.

Therefore, I stick with blue for unvisited link in dark mode (but make it brighter to meet AAA rating) and change gray to a pale pink with a hint of purple.

The other PR is to change the search bar color in dark mode. There is no config for dark mode hovered search bar. Therefore, the color is using the same one with light mode. I changed the color based on the same design pattern with light mode (same color with background but use border to tell apart).

These couple of weeks gave me lots of chance to work with user accessibility and I enjoy it. I took over another user accessibility issue and will be discussing with other developers to file more specific improvement issues.

DX

When I was shipping this PR to bring back our admin button in UI2.0, I found that the old method to run login server does not work. The reason is that we're in the transition to change to microservice. There are easier ways to start the needed services separately.

After talked to professor Dave, he suggested me to write a new document to help other developers handling these environment setups. (Since this is the second time I asked him about it)

In this PR, I gather different scenarios and explain how to do env setup and explain why we do that. It is challenging for me since I need to read other people's code and to understand. This PR is still in progress, I hope I can get more people to review it and get it merged!

What are users thinking

Yuan-Hsi Lee — Sun, 21 Mar 2021 00:26:46 +0000

This week, Pedro discussed his thoughts with me about the title design in telescope. He wants to make the title section smaller.

This is how telescope handling the post title,

The title stick to the top when you scroll up, so that you can always see the title while you keep scrolling down and reading the post.
If the title length is too long, we wrapped it with ...; and it can be expanded after user click the title.

However, once the title is expanded, the title section is twice big. It'll occupy too much space of the screen.

It's smart to find out this issue. I have little knowledge of user experience, so I never figure this out. This is a great chance for me to dig into this field.

The solution Pedro came up is to dynamically adjust font size. In the other word, when the title overflowed, the font-size will be adjusted to be smaller and able to fit the div element.

We've tried different approaches to make it work, but none of them came with an expected result. Therefore, we were thinking removing the sticky title feature. As Dave suggested, when we're making changes on the UI design, we should always consider user's "habit". For example, in other similar kinds of websites, how do they design this feature? Users usually get used to one kind of design in a specific type of website. There, browsing other blog-post websites about how they handle a long title is a good way to start.

In medium and dev.to, there is no sticky title design. The title goes to the second or the third line if it's too long. However, it's not the same as our telescope. We have only one timeline, gathering all the posts (the whole post, without "read more" feature) from different authors.

In the meeting, some team members said that they don't really need the title once they start to read one post; but some do. The team came up with a solution which is to make the font-size of title smaller so that in most cases, the title will remain one line. Our title font-size is about 3 times bigger than the content font-size. To compare with some similar websites, they're doing much smaller size for their title.

Better? Can you still tell this is a title of the post?

Biweekly release makes us keep shipping changes. Sometimes, there is no perfect solution for one issue. But, shipping changes in each release makes our project better and better, even if it's just a small change in every release.

Telescope 1.8 Release

Yuan-Hsi Lee — Sat, 13 Mar 2021 02:10:47 +0000

Release 1.8 for telescope is quite of a special one, because GitHub was down in our scheduled release time. According to our experienced professor, this is the first time he has ever seen GitHub down like this. I assume I'm lucky to see this in my first year of open-source.

Therefore, we did the PR review through video call. It was surprisingly efficient. We fixed our PRs and tried to get them passed to 1.8 release.

The issue I want to talk about is add the avatar component. The plan for avatar is to integrate with GitHub so that we can get users' profile picture. Before that, we still need a temporary avatar to replace the blank circle like the below picture.

Pedro suggested the avatar component from evergreen. But Dave wanted to stick with what we have, which is material-UI, there is also avatar component from material-UI.

However, material-Ui avatar component only provide a circle, it doesn't generate initials with the given name value, we'll need to generate it by ourselves. Therefore, my task is to wrap the material-UI avatar component with customize functionalities.

We want to make our avatar component to accept author name or image value. Image value is preferred, but if there is no image value, we'll take name value instead, and generate the initials for the avatar.

I want to talk about how to generate initials. I checked evergreen's avatar component code, it actually generates initials by the first 2 words in the name. It might work for most cases since most people have 1 word for first name and 1 word for last name (e.g. Piper Chapman). However, there are still some people having more than 2 words in there name, it could be a long first name with multiple words, or middle name.

The other problem is, should we use space or hyphen to separate the words in a name? This is a comment I got in my PR. Personally, I'd use space instead of hyphen. Hyphen is more like linking words to one part of name.

My initials generator code looks like this,

const initials = name.split(' ')
                     .map((splitName, i, arr) =>
                     i === 0 || i + 1 === arr.length ? 
                     splitName[0].toUpperCase() : null)
                     .join('');

This generator will separate words in names by space, and ignore the words other than first name and last name. splitName represents the current value, i represents the index of it, and arr represent the whole array of splitted names. i === 0 takes care of the first word of the name, and i + 1 === arr.length takes care of the last word of the name. For example, my friend Abu from OSD600 has 5 words in his name (Abu Zayed Kazi Masudan Nabi). His initials will be AN, instead of AZ. And for me, my name is Yuan-Hsi Lee, there is a hyphen in my first name to link 2 syllables, therefore, my initials will be YL instead of YH.

Above are how the name initials avatar look like.

The other PR which is related with this one is to centre the initials text. Somehow, this font makes the text slightly toward the top. Thanks to Anton, Ilya and Minh's help, the puzzle is solved and the solution is made.

Telescope 1.8 Release

Yuan-Hsi Lee — Sat, 06 Mar 2021 03:18:48 +0000

After midterm week and study week, it's time to plan for the 1.8 release of telescope. In this post, I want to talk about my plans and the projects that I'm looking forward to seeing them be implemented in the release.

In the last release, I was working on updating dependencies and the auto-update tools including Renovate and dependabot. After working with that, I started to have an interest in GitHub CI/CD, and plan to learn to write GitHub action.

In OSD600 (the first open-source course that I took in Winter 2020), we implemented GitHub action workflow to apply code formatter and linter to our repo by selecting template .yml file to create our needed actions.

When working with dependabot, it also uses .yml file to implement GitHub actions workflow.

After introducing dependabot, the PR that was generated by dependabot is a bit of confusing for contributor. For example, what should we do for the PR? How to test it? Isn't the major bumping to risky? What to do if the bumping causes test failure or error?

Therefore, I wrote a document to explain a simple workflow for handling dependabot PRs.

However, it will be more convenient to append the documentation with the PR so that contributors can read the document when they're reviewing the PR.

Currently, it is not possible to customize the description of dependabot PR. Therefore, I tried to append a comment with the link of dependabot documentation whenever the dependabot PR is created.

The other challenge for me in release 1.8 is about UI 2.0. Thanks for my team member Pedro assigning me a CSS and JS involved issue. The issue is to adjust font-size dynamically in order to fit the title div size. For example, if the default font-size causes the title overflow (which means the title is too long), the title's font-size should be set to smaller size in order to display the whole title with any wrapping. This is a very interesting issue. After research, in order to adjust the font-size by character number, the scrollHeight and the clientHeight will be involved. By comparing these 2 value, we can get the result of if the text is too long, then, we adjust it's font-size, until the text (title) can be fully displayed.

Currently, I'm trying different plug-ins and to write a function myself. Hopefully, I can finish this feature by release 1.8.

Update Dependencies by Human and Dependabot

Yuan-Hsi Lee — Sun, 21 Feb 2021 21:23:28 +0000

Last week, we brought a new member, dependabot, to our project. Everything looks great, and he did his job perfectly. However, due to the large amount of dependency updating PRs (approximately 40 PRs was created when we added dependabot that day) and the automatic rebase feature, all the PRs sent by dependabot keep rebasing whenever there is a new PR merged to master branch. This unfortunately broke our CI, and we had no choice to let him leave.

Since dependabot left, I got my old job back. I manually updated about 35 outdated packages. Surprisingly, most of them did not break a thing in our project, even the major ones. I follow these steps to update dependencies,

Read CHANGELOG.md or release note. This will help you to have basic understanding of the new version of packages
update the dependency with npm i <package-name>@latest
run test units and look into fails if any. The knowledge from step 1 is helpful here.
if tests are all passed, run the application make sure all the functionalities are as good as old time

There was only one dependency did pass the test, which is bull-board. Our old version was 0.9.0 and the latest version is 1.3.1. Version 0.9.0 is not only outdated, but also cause a warning because of its dependency, highlight.js. Version 0.9.0 of bull-board uses version 9 highlight.js. Therefore, even if we have updated our highlight.js to version 10+, the highlight.js in bull-board is still version 9 and causes the warning.

  Verion 9 of Highlight.js has reached EOL.  It will no longer
  be supported or receive security updates in the future.
  Please upgrade to version 10 or encourage your indirect
  dependencies to do so.

  For more info:

  https://github.com/highlightjs/highlight.js/issues/2877
  https://github.com/highlightjs/highlight.js/blob/master/VERSION_10_UPGRADE.md

Therefore, this update of bull-board is critical.

However, from bull-board 0.9.0 to 1.3.0, there are some major changes, such as they switch to typeScript from JavaScript. These changes from newer version didn't pass our tests.

Here are the changes I made,

1.Include BullAdaptor due to the change of API

// okay with old version; not okay with newer version
const { setQueues } = require('bull-board');
setQueues(queue);

// fit with new version, new API
const { setQueues, BullAdapter } = require('bull-board');
setQueues([new BullAdapter(queue)]);

2.Change middleware

// old
const { UI } = require('bull-board');
router.use('/queues', protectAdmin(true), UI);

// new
// router: bullBoardRouter is to solve the naming conflict with router from expressjs
const { router: bullBoardRouter } = require('bull-board');
router.use('/queues', protectAdmin(true), bullBoardRouter);

Eventually, I updated all the outdated dependencies before release 1.7. Release 1.7 is also where we get rid of Gatsby front-end and use Nextjs front-end, which is quite a meaningful release. I'm glad we can have a fresh start in this release with new front-end and all dependencies updated.

After Anton's modification of dependabot config, dependabot's PR limit has been narrowed down to one from a package file. Moreover, the automatic rebase feature is turned off. Even though this will bring us more work to manually rebase the dependabot PRs, this is the best solution for having dependabot and not breaking Github CI at the same time.

Automatically Update Dependencies

Yuan-Hsi Lee — Sun, 14 Feb 2021 04:17:35 +0000

This week, I was working with automatically updating dependencies for projects. Well-maintained packages release new versions frequently, in order to get more features, bug fixing, and improvement in general, we usually want our project to have the latest version of packages. However, it is overwhelming when you have hundreds of packages to update.

In GitHub, there is a tool called dependabot. It is like a robot helping you find out any security vulnerability. Moreover, it can also help you to update the outdated packages with proper configuration.

Telescope had a dependabot for sending PRs when there is a security vulnerability. But, it didn't send PRs when there are outdated packages.

A team member Anton wants to add this feature for our project, to have automatically generated PRs when there is any outdated packages. I'm also interested in this, therefore, we had a discussion about how we can apply this feature to our repo.

Professor Dave mentioned one tool called Renovate, which is a very similar tool like GitHub's dependabot. Therefore, we decided that Anton try dependabot on his GitHub repo; and I try Renovate on my Github repo.

We came up with couples of basic requirements for this automatically sending PR for outdated dependency thing.

Able to set schedule (e.g. daily, weekly; and specific time or time range) and proper time zone
Auto-assign reviewers
Format commit message

And some nice-to-have but not mandatory features,

Auto-merge PRs for patch (e.g. 4.8.4 to 4.8.8)
Specify GitHub labels to PRs

Renovate bot is able to do every thing on this list. It is also very configurable. After install renovate through GitHub application, renovate bot will send a PR in order to merge a renovate.json file to your repo. This file is where you configure the automation bot setting. The default one looks like this,

{
  "extends": [
    "config:base"
  ]
}

The default setting will scan through your repo, finding out every package files, not just to root! For example, in our telescope project, there are more than one package files hold our current version of dependencies; and renovate is able to find all the file.

To change the default setting, renovate provides lots of configuration options. I change my renovate.json to something like this,

{
  "extends": ["config:base"],
  "timezone": "Canada/Eastern",
  "schedule": ["after 7am before 9pm every weekday"],
  "reviewers": [
    "c3ho",
    "manekenpix",
    "raygervais",
    "cindyledev",
    "team: Seneca-CDOT/Winter-2021-Telescope"
  ],
  "npm": {
    "packageRules": [
      {
        "matchUpdateTypes": ["minor", "patch"],
        "schedule": ["after 7am before 9pm"],
        "automerge": true
      }
    ]
  }
}

As you can see, renovate has the configuration to set time zone, arrange schedule, and assign PR reviewers (can assign to individual github username or team name). Moreover, we can specify which type of package file (e.g. npm or docker) that we want to make special schedule or features like auto-merge; the type of package update (major, minor, or patch) can be configured as well.

Comparing with GitHub dependabot, they can both meet our requirements. Auto-merge is a bit of complicated in dependabot, but still doable. However, after discussing with team, we don't need auto merge feature for now (still manually testing all updates no matter its type). We decided to go with GitHub dependabot since it has all the feature we need, and it's integrate with GitHub.

This is my first time working with something like auto-bot and I honestly do enjoy it. I'm thinking about learning more in this field. Thanks the team and Anton for giving me this chance to know something cool!

How Many Releases Do We Need?

Yuan-Hsi Lee — Sat, 06 Feb 2021 04:51:58 +0000

We just got our telescope 1.6 release this afternoon! Ya!

I want to talk our new header (including menu bar and logo) ported to the Nextjs front-end (we're moving our front-end stuff from Gatsby to Nextjs). It's amazing to see the Nextjs front-end to have about 70% similar with the old Gatsby front-end. The reason I want to talk about it is how the developer work on this issue when he got stuck. He reached out on Slack and there happen to have people having time to debug with him, they even had a 3-hour screen-sharing meeting to code together. This is something that I always want to do but never get a chance to do so. Before the pandemic, it's easy to check on each other's work when you're in the same room. You could just stand up and walk to your team member's desk and ask her for help. In this pandemic, it's impossible to gather and meet up as a group.

Anyways, what I want to discuss is, after merging this PR, we found some bug in this newly ported header. For example, the logo should be a clickable link and lead us back to home; but it isn't. And, some CSS styling is not consistent. We still push it to our 1.6 release today. And we'll be fixing these small bugs in the upcoming release. This is quite different compare with what I thought about release. I always think, there should be some criteria about a specific release, and we have to make it before the release date. The thing is, people are not perfect, and there is always something we can't expect or control. The goal of release is to make it on that release date, instead of waiting for everything is done. Because there will never be one day that everything is done, it's not possible. We'll always come up with new ideas for enhancement or find some new bug that we didn't notice before.

No matter how careful we were before merging a PR, we sometimes forgot things. The good thing about working as a team is we can always check each other's works, finding bugs, and fixing them. It's even better when doing an open-source project, more people are helping you to check your code! How many releases do we need for a project? There is no answer. As long as we want to make the project get better and better, we need more releases to do so.

Package Version - Update or Not Update?

Yuan-Hsi Lee — Sat, 06 Feb 2021 01:54:19 +0000

Packages are helpful and sometimes critical for projects. However, packages have new release all the time, so as their dependency packages. A developer should learn how to determine if we need to update the latest version of packages or not.

I've been checking on something like this these days. There is a warning while building the telescope project, it complains about one of our package is too old to get supported. And this old version package is one of the dependency of the other package. Therefore, we need to look into both packages' new versions and see if the new version of packages can fit in our project; and if they can't, how to modify our project or should we look into other packages?

Also, it's a big work for checking all these outdated packages. Should we check each of them and see if the update breaks our program? Should we build a bot to always update the packages automatically when it's just a minor update (such as 1.6.7 to 1.6.8)? Does automatically updating packages save our time or give us more work (to fixing it) in the future?

There are a lot to think about when it comes to maintaining a project with its packages. I'm glad that I have this chance to dig into this new field :)