My original goal for Release 0.4 was to contribute real code to a large open-source project related to finance. I completed that goal by working on Actual Budget, which is a fairly big project with around 23k stars.

Thoughts About the Future

Now that I understand the workflow better, I hope I can eventually try adding a feature or modifying core code in a large codebase. I’m also paying attention to bigger finance-related libraries such as QuantLib, and maybe one day I will be able to contribute there as well.

Overall, I would say I accomplished what I wanted for this release — just not as fully as I expected. But it’s still a good start.

How I Worked Through the Problem

Most of my technical work is understanding the project’s structure and figuring out how to safely fix the type issue. One important thing I learned was that the .d.ts files inside /node_modules/@actual-app/... are not the source code, even though ESLint and TypeScript errors pointed me there.

*.d.ts files for the issue desc

These files only describe the types, so the real fix needed to be applied in the actual source files with the same paths (not totally same).

… And their corresponding original files

Another useful technique I learned was compiling files directly using tsc. By compiling only the files I changed, I could quickly check whether the error was fixed.

But since I had to temporarily update the config to include my test files, it was easy to break something by accident. In this case, I relied on Git to get rid of all temp files and keep the repo clean before submitting the changes (To be honest, creating a totally new test branch is another good idea).

I must mention that, the “fork first, then work separately” workflow we learned in class this semester did help me a looooot for managing my chaotic developing process.

Community, Communication, and the Open Source Mindset

After watching my classmates’ presentations, I realized that mastering a specific language is not the main requirement for open-source contribution. The real skill is always the communication: reading existing discussions, following instructions, asking questions when unsure, and respecting the time of maintainers.

Large projects usually have clear contributing guides, and Actual Budget is no exception. Their documentation explains workflow, expectations, and review rules in detail. As contributors, our responsibility is to follow these instructions first before doing anything else. Good communication keeps the whole project running smoothly; ignoring guidelines only creates extra work for others.

My PR also helped me experience the interaction between contributors and automated tools like Copilot, Coderabbitai, and many other review bots. They gave suggestions and asked for tests. Sometimes I felt a bit frustrated that I couldn’t discuss things with a real human; however, if I can solve the issue with bots alone, I guess it means I did a pretty good job, right…?

Overall, this release helped me understand more about two key concepts of the open source community: communication and respect.

I really enjoy the friendly and efficient communication among the contributors.

🔔 Prelude: Me working with a big project… Wait, me?

Starting the Contribution

This week I finally moved from planning into actually contributing. I decided to work on Actual Budget again, and honestly, I was kinda nervous because this repository has 23.6k stars, real users, and an active core team.

I chose a TypeScript issue related to incompatible type definitions

(https://github.com/actualbudget/actual/issues/6290).

In short, the Query type was missing a few methods and caused type errors inside the API package.

My PR is small and touches only a few lines of code (PR: https://github.com/actualbudget/actual/pull/6331). The challenge was not writing the code only, but understanding what the project expected from contributors.

Understanding the Project and the Rules

Before writing anything, I spent most of my time reading the project structure and the Contributing guide. Actual Budget has an entire website explaining how to participate:

https://actualbudget.org/docs/contributing/

Compared to our previous workflows, the overall process is similar — fork repo, create branch, implement change, send PR. However, the attitude and expectations are much more formal.

The contributing guide explains:

• development workflow
• expectations for PR quality
• how reviews work
• and, very directly, that not every PR will be accepted

“We aren’t going to take every single little change. Don’t be offended if we close your PR…”

So even for a small fix like mine, discussion might still be required, and reviewers could ask for adjustments. It’s more serious, but also very professional.

In addition, I got in touch with yarn in this project, and the project has a set of commands to generate a release note instead of describing PR on GitHub.

The PR Experience

After pushing my code, I first marked it with [WIP]. Soon after, Copilot automatically reviewed the PR and suggested writing tests. That’s kind of strange because when I checked the file, I found there were no dedicated tests at all for that file, so I asked the question directly inside the discussion and waited for a reviewer to reply.

When I removed [WIP], another automated reviewer (coderabbitai) appeared, plus almost 30 checks waiting to finish. Seeing that number made me feel how large and complex this project really is.

So far, the review and discussion are still ongoing.

Final Thoughts

Even though this PR is small, the experience means huge for me. I got to know about how large open-source projects manage quality and how serious review standards can be.

I also feel more confident contributing to large projects now. I’m planning to share more details and personal reflections during Friday’s meeting, and hopefully continue contributing after Release 0.4.

🔔 Prelude: Tough week, and it will get tougher

Planning for the release 0.4

Last week, we wrapped up some final tasks for Release 0.3, and now I’m officially moving into the work for Release 0.4. I mentioned earlier that I was still waiting for my PR for Release 0.3 to be merged. Fortunately, right after the lecture, someone from Opsimate finally reviewed my changes and gave me feedback. The response time was a bit slow, but at least things are moving again.

The real issue, however, is the schedule. The end of the semester is approaching, and last week I was completely occupied with assignments from other courses. Because of that, I didn’t spend as much time exploring Release 0.4 as I had hoped.

The good news is that during Release 0.3, I had already identified a few projects I really wanted to contribute to: My last post. I also spent some time understanding their codebases, so I’m not starting from zero. I’ll talk about those projects below.

My plan is to clear out the most urgent schoolwork first, then fully commit myself to Release 0.4.

Microsoft Qlib

I already finished setting up the environment using pyenv and uv, which allows me to manage Python dependencies very cleanly. I also prepared the example dataset used in the project.

My next step is to go through the latest issues on their GitHub repo and see if there are any that interest me or are suitable for my skill level. Once I choose an issue, I can start analyzing the relevant parts of the code.

I don’t intend to fully understand the entire codebase, because Qlib is large and complex. Instead, I plan to learn the sections that are directly related to the issue I want to work on.

Actual Budget

When I was reading the code earlier, I actually found an approach for solving this issue: https://github.com/actualbudget/actual/issues/6149

However, the problem mainly involves the UI, and the fix probably requires only around ten lines of code(In fact, the existing PR for this issue modifies fewer than 20 lines.) Because of that, I eventually decided not to work on this issue, since it feels too small for Release 0.3.

My next step is to continue exploring the parts of Actual Budget’s codebase that I already understand and look for issues that are more meaningful to contribute to.

One thing I realized while reading the code is that in a well‑designed project, adding a new feature—even a large one—doesn’t necessarily require changing many lines of code. The architecture handles most of the complexity. For an assignment, this might make the contribution look “too small on the surface,” but the real difficulty lies in reading and understanding the existing code.

🧳 Summary

In my current plan for Release 0.4, I expect to focus mainly on these two projects. The most difficult part for me right now isn’t the code itself, but managing my time during this extremely busy part of the semester.

I hope everyone in the course has a smooth development process, and I’ll try my best to push forward as well.

🔔 Prelude: Rocket lift off

Answering Main Lab Questions

Originally I had a reflection section for this blog, but my Professor provides some wonderful questions for me to share my experience and thoughts, so, my reflection has been melted into my answers. I hope you can find useful information directly in there.

• Which release tool and package registry did you choose? Provide links to everything you mention.

  • Go has it’s unique release system — basically, if I init my module locally, push to the GitHub, have a right git tag version, and finally click the “Request” on https://pkg.go.dev/example.com/my/module … then, done, I don’t need to handle rest things, the module will be indexed on the official module platform, and anyone should be able to go install my module. So convenience.

• What was the process for creating a release? Be detailed so that other developers could read your blog and get some idea how to do the same.

  • Ok, assume that you already have a “ready-to-go” codebase (you cannot release empty folder)
  • Then, you should use git tag related commands for tagging you current commit (Use git tag --help for help)
  • Next, you should push your commit to GitHub, maybe you have already done that, so, you should push your tag separately to GitHub
  • Don’t forget to change your documentation… I used to notice that my release still shows v0.0.1 for the version flag, which means I have to repeat my work again (depressedly).
  • Finally, you can release your package. I used Go, and put some useful links in the Reference section. If you are also using GO, them can help you make your way.

• What did you learn while doing your release? Did you have any “aha!” moments or get stuck?

  • A lot of “aha!” moments, actually.
  • Go’s release workflow feels almost suspiciously simple—so simple that sometimes I overthought things.
  • The biggest challenge wasn’t complexity but the danger of skipping steps because the process looked too easy.
  • You can find more of my “aha!” moments in the detailed experience I describe below.

• How much did you have to alter your code, files, build, etc. to use the chosen package format and registry?

  • I didn’t need to change my code structure at all (But actually, I still need to change the documents).
  • Go’s build system is easy, clean and straightforward. I think this is one of the reasons many developers love Go — compared to languages like C++, incremental builds and direct code fetching “just work.” (Disclaimer: I also really like C++.)
  • One thing to be careful about is that git tags must follow the vX.X.X format, such as v1.0.1. Otherwise, the Go package platform may fail to recognize the version or cause unexpected issues.

• How did the User Testing session with your partner go? Describe what it was like, where they got stuck, and how you corrected the problems.

  • Before the session, I tested installation myself on my Raspberry Pi.
  • Interestingly, because my package URL is https://pkg.go.dev/github.com/BHChen24/repo2context, the default installed binary is named repo2context, not the short alias r2c that I used throughout my documentation.
  • This confused both me at first — I couldn’t find the installed executable because I was searching for r2c.
  • To avoid further confusion, I updated my README to explicitly mention this and show how to rename the binary if users prefer a shorter command.
  • Still waiting for feedbacks from my partners

• How do users install and use your project now that it has been released? Provide links and some instructions.

  • I have provided full installation instructions in my README:

  ## Installation
  
  ### Prerequisites
  
  - [Go](https://go.dev/) installed on your system
  
  ### Quick Install
  
  ```bash
  go install github.com/BHChen24/repo2context@latest
  

  This installs the binary as repo2context to your $GOPATH/bin (or $HOME/go/bin by default).

  Add Go bin to PATH (if not already configured):

  Linux/macOS:

  # For bash
  echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.bashrc && source ~/.bashrc
  
  # For zsh
  echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.zshrc && source ~/.zshrc
  

  Windows (PowerShell as Administrator):

  [Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\go\bin", "User")
  

  Then restart your terminal.

  # Verify installation
  repo2context --version
  
  # (Optional) Rename to shorter command
  mv ~/go/bin/repo2context ~/go/bin/r2c
  

  
  I found once my app is released on the go pkg platform, all these instructions also appear on the home page, which is really cool and convenient. I put it again here for you to quickly navigate: [https://pkg.go.dev/github.com/BHChen24/repo2context](https://pkg.go.dev/github.com/BHChen24/repo2context)
  

References

• https://pkg.go.dev/about#adding-a-package
• https://semver.org/

🔔 Prelude: Bugs in the middle of the way

OpsiMate bugs fixing

During the development of the new Coralogix integration, I ended up discovering two UI bugs — because of course things like this always happen, right?

1. The first issue was a missing icon. This one was extremely small: a one‑line fix in a single file. Honestly the PR felt almost too tiny.
2. Fortunately, another bug appeared at exactly the right time. This one involved a UI element that refused to trigger properly, which required a bit more investigation and work.

Missing dog

1. In my first blog post, I mentioned that OpsiMate includes a DataDog integration. Ironically, the dog went missing

   

   Where is the dog?

2. I attached the screenshot directly to the issue. It more or less explains the entire situation by itself https://github.com/OpsiMate/OpsiMate/issues/557.

3. I wasn’t sure if I had to follow the full issue template… describing such a simple visual bug felt also a little bit painful.

4. The fix was straightforward, and again, a screenshot was enough to show the completed result: https://github.com/OpsiMate/OpsiMate/pull/560

   

   Doggy is back!

Indifference button

1. The other issue was a button labeled “Add Provider” that refused to open the sidebar.

2. While researching good tools for recording UI interactions, I discovered ScreenToGif: https://github.com/NickeManarin/ScreenToGif . It turned out to be incredibly useful, and I used it to record a small gif video and attach it to the issue.

   

   So easy for using

3. You can see the lively demonstration right in the issue: https://github.com/OpsiMate/OpsiMate/issues/558. It’s one of those situations that is very hard to explain clearly with text alone.

   

   Wow I can also insert it here!

4. The root cause was improper state management. Once I identified which component and function were supposed to be triggered, the fix itself was not too difficult.

Reflects

Overall, even when you focus on a single PR, bugs still have a way of appearing continuously (sadly). There’s never a shortage of issues to work on — you don’t have to worry about “running out” of them.

🔔 Prelude: API document reading — totally as hell

Coralogix Integration

What is it?

According to the official description, Coralogix provides “real-time insights and trend analysis for logs, metrics, and security data with no reliance on storage or indexing.”

In simpler terms, it is essentially a real-time server monitoring and observability service. Coralogix helps track logs, visualize metrics, and detect anomalies without requiring developers to manage complex storage systems. For projects with active deployments, this kind of integration makes debugging and performance monitoring much easier.

Coralogix’s Main Dashboard

My main task is to first fetch all the dashboards’ information to support further features.

Challenges

1. Reading the API documentation turned out to be much harder than I expected. As shown in the screenshot：

   

   API Docs

   The example on the API usage page points to https://api.coralogix.com/. However, when I used this endpoint, I didn’t receive any meaningful response—only an API key permission error.

2. I went back to the dashboard and expanded my API key permissions all the way to the admin, but the error still appeared. That was when things started feeling really strange.

3. Since the issue clearly wasn’t about permissions, I began to suspect the endpoint itself. It didn’t make much sense that everyone would use the same entry point. So I spent a long time digging around the documentation… and eventually found the endpoint control page: https://coralogix.com/docs/integrations/coralogix-endpoints/

   

   End Point demonstration

4. I was a bit frustrated — why wasn’t this mentioned anywhere on the main API page? And because the service is still relatively new, there is almost no discussion online; even AI tools didn’t help much. Honestly, I think it was part luck and part persistence that led me to the correct page. Otherwise, I would have wasted much more time.

5. By the way… there are also outdated API references still visible in the docs

   

   Huh?

   which makes things even more confusing.

6. Through this experience, I realized how important high-quality developer documentation is…

Fixing

1. To implement the new feature, I mostly referenced another integration in the project : https://github.com/OpsiMate/OpsiMate/blob/main/apps/server/src/bl/integrations/integration-connector/datadog-integration-connector.ts.

   Their implementation was very clean, so I could follow the structure and focus mainly on handling the data — the request and response parts.

2. And although the Coralogix documentation has some organization issues, the API page itself is straightforward. It clearly shows the response format, and the examples are easy to follow:

   

   A clear API response

   This made writing the actual code much easier.

3. Apart from the time I spent searching for the correct endpoint, the actual development process was quite enjoyable. Nothing beats the satisfaction of running a curl command and finally seeing the server return the correct data.

🔔 Prelude: I have a bad feeling about this: once again, I find myself stuck trying to choose the right project.

Main Content

Still WIP

At the end of this week, I haven’t submitted my first PR yet. Most of my time went into searching for a suitable open‑source project, and my plan is to update this post again after I finally publish my first PR.

Since I previously mentioned that I want to contribute to a repo related to $finance$🤑, I spent a good amount of time exploring that topic. Here are some projects currently on my list:

AI-powered investment platform

Microsoft Qlib (https://github.com/microsoft/qlib)

Qlib describes itself as “an AI‑oriented quantitative investment platform,” but in simpler words, it’s a framework that provides data tools, modeling support, and workflow automation to help build AI‑driven quantitative trading strategies.

• I’m personally very interested in this project and have already started exploring it. The development activity is not bad — issues and PRs are still being handled as recently as this week.
• It uses Python, has plenty of issues to choose from, focuses on a hot topic (AI), and the documentation is fairly complete.
• But…I spent an entire afternoon debugging my Python environment. Absolutely terrifying.

Open‑source banking system

Apache Fineract (https://github.com/apache/fineract)

• This is an open‑source banking system written in Java. I feel that its tech stack aligns well with what employers in the industry expect. If I can learn its design principles and make meaningful contributions, it could be very helpful for my future job search.
• However, the repo doesn’t have a typical Issues section, and its contribution rules seem quite different. I might need extra time to figure out how to get started.
• Still, this is the project I’m currently most interested in.

Personal-finance app

Actual Budget (https://github.com/actualbudget/actual)

• This personal finance platform is super active: around 30 PRs were handled within just a week, and it has around 23k stars. Clearly a very popular project.
• It mainly uses TypeScript and focuses on “practical frontend” features. The demo isn’t such fancy, but the features look solid and well‑built.
• It doesn’t feel “technically fancy” or groundbreaking, but it solves real problems — exactly the type of project I care about and would like to contribute to.

🧳 Summary

Overall, I’m still in the process of selecting the right project and diving into the code, but I’m getting closer. Hopefully I can finally report back with my first PR on weekend.

Updates

Over the past several days, a few things happened that changed the direction of my work.

1. At first, I planned to continue exploring Qlib. However, when I tried to set up the environment, uv and pyenv ended up conflicting with each other again.
2. I spent additional time rebuilding a clean environment, but unexpectedly, Python packages started throwing compilation errors—some of them simply refused to build.
3. At that point, I felt I had already invested too much time just dealing with environment issues. So I decided to switch back to a project I’m more familiar with: OpsiMate (https://github.com/OpsiMate/OpsiMate ), which I worked on during release 0.2.
4. While reviewing feature requests, I found an issue that has not been implemented yet: https://github.com/OpsiMate/OpsiMate/issues/94 . It’s new, has reference implementations, and involves a reasonable amount of work. It felt like the right fit, so I decided to focus my efforts on contributing to OpsiMate.

🔔 Prelude: Another helpful hand, and more

Main Content

This week I worked on GtHub Actions CI for my Go project, added a Go linter, and wrote tests for a partner’s repository. The lab overlapped with my Cloud Computing (CCP) course, so the CI work fit well with what I’m learning there.

Reflections

• I’m also taking CCP, so CI-related tasks felt practical.
• I had already added CI in a previous lab (I thought “why not?” while I was adding tests), so I extended that work here.
• Adding a Go linter was new to me (I know the eslint), but following the golangci-lint repo made it straightforward.

Answering questions

How did you set up your GitHub Actions CI Workflow? What did the YAML for this workflow look like?

I searched “How can I set up my GitHub Actions CI Workflow?”, as just same as the question title. Then, I found a Go workflow templates by clicking the action button in GitHub. The workflow builds and tests on push and pull requests to main and dev. Super straightforward again.

Template YAML:

name: Go
on:
  push:
    branches: [ "main", "dev" ]
  pull_request:
    branches: [ "main", "dev" ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set up Go
      uses: actions/setup-go@v4
      with:
        go-version: '1.25.1'
    - name: Build
      run: go build -v ./...
    - name: Test
      run: go test -v ./...

How did your partner’s repo and testing setup differ from yours? What was it like writing tests for a project you didn’t create?

My partner’s repo did not initially have CI now(I will check again later). They did provide example tests, which helped me a lot. Writing tests for someone else feels just like writing a feature, but you must understand more about the intended behavior before you can test it well.

What do you think of CI now that you’ve set it up for yourself?

• CI acts as an automatic safety layer — it finds flaws before the changes are really applied to the main (or other danger zone).
• It saves manual steps: every push triggers the same checks.
• CI is also flexible: you can configure testing closer to the real deployment environment, which local runs can’t always match.

If you did the optional challenges, talk about how that went and what you learned.

I added golangci-lint via GitHub Action (the repo/documentation has a ready template). Check their repo and instruction: https://github.com/golangci/golangci-lint-action

I was surprised when I found they actually have provided “ready-to-use” config lines that allow me to copy and paste and then run everything correctly.

Lesson: read official docs and search the marketplace before creating the wheel — many reusable actions already exist.

🔔 Prelude: Code everywhere, tests everywhere, tokens everywhere, budget nowhere

Main Content

Testing commit:

https://github.com/BHChen24/repo2context/pull/36/commits

Answering Lab Questions

• Which testing framework/tools did you choose? Why did you choose them? Provide links to each tool and briefly introduce them.
  • Since I my project is written by Go, so I just use the go test for testing: https://pkg.go.dev/testing
  • As described on the official page, it “provides support for automated testing of Go packages.” It’s also a part of the standard library, so it can be used directly when the Go environment is set.
  • At the beginning, I put the test files in another folder just like what I used to do with Typescript testing, but then I found it’s better to just place them beside the source code as a standard way in Go projects.
  • Use go test [target folder/file] to run tests, and use go test -cover [target] to see the test coverage
• How did you set them up in your project? Be detailed so that other developers could read your blog and get some idea how to do the same.
  • See above~ :)
• What did you learn while writing your test cases? Did you have any “aha!” moments or get stuck?
  • I felt writing tests is painful.
  • I have to consider each possible way to trigger an error, which is literally difficult to cover all the cases - also means I have to fully understand the tested target (mostly functions in Go).
  • Always, when I hand my tests to AI for reviewing, it will give more comprehensive test cases, like missing values, edge cases, input format, etc. I did learned a lot.
  • But I also begin to doubt that I can really memorize all useful cases. There are at least 10 to 15 cases for each function, even though there are some common cases I can reuse.
  • Maybe a test cases document is the truly practical tool for the testing.
  • I also made good use of “given-when-then” pattern for writing the tests. (See https://github.com/BHChen24/repo2context/blob/main/pkg/scanner/scanner_test.go) It’s super helpful for planning the test process.
• Did your tests uncover any interesting bugs or edge cases?
  • No for this time. But I am curious about why I didn’t find any bugs… Maybe more tests will reveal some, or I need more time to review my tests.
• What did you learn from this process? Had you ever done testing before? Do you think you’ll do testing on projects in the future?
  • Actually I have done the tests in the Lab6 (See https://github.com/BHChen24/repo2context/blob/main/pkg/tokenCounter/tokenCounter_test.go)
  • At that time, I just simply thought that, “oh, since I will develop a new feature, maybe developing the tests at the same time is a good idea,” and then I created the tests beside it.
  • I think doing the testing is a standard step for developing reliable applications, so I definitely will do that in my future projects.
  • But I am actually feeling weird… Since each test case can be different, I’d like to say I’ve learned a lot from past tests, but for the next test I may still go blank with the new situation… Even though I know how to apply the test pattern, most of the time I still need to find some references to implement the test logic. Is it normal or not?

Experience with Speckit

As the additional content, I’d like to mention the new AI related tool called **Speckit, built by GitHub.**

Speckit installing screen

This week, I tried it on my project and generated some scope-focused documentation for adjusting the AI assistant’s behavior towards my project.

Tldr, it looks good, but it didn’t reach my expectation for budget and left some confusion about how it understands the project context.

Firstly, as a CLI tool, it can generate corresponding commands for popular AI assistant tools such as Claude Code, Codex CLI (I use cursor-agent cli), and then, helps you to generate the project documentation. Which means you still have to call the api for creating the docs, and it has a lot of strict rules:

To-do list for generating plans

As you may see, besides the plan, we also have constitution and specify that need to be created before, and then we have tasks to generate, finally implement it.

The full chain is constitution → specify → plan → tasks → implement; they all could be generated or run in the chat box with the AI assistant by slash commands like /speckit.* [your chat content].

The quality of documentation is fantastic, as you have all the practical built-in rules in the speckit:

A lot of .md files

Good project understanding and constitution set up:

Nearly wonderful and comprehensive documentation

And quality checking:

But, the token consumption is also beautiful:

3 million token cost in minutes

At that point it exactly hit me like: for some project this small, Speckit steering the ship was overkill.

In addition, it did help me to create a new branch for implementing new test:

Helpful hand

However, it ignored my git context and named “001-test-xxx” (implicitly pointing to issue 1) the new branch, while I am currently at the “33-add-more-tests” branch. I think it’s just, not perfect, though I still paid a lot of token.

In the end, I found the Speckit is a really practical tool - there’s so much documentation for the AI to follow, that its behavior stays nicely in check (though I still think any AI-generated docs need a human adjust). However, for a small personal project like mine, I haven’t felt a huge payoff yet.

If you are interested, you can also have a try on it in your projects. :>

🔔 Prelude: Journey of open-source contribution

In October, in Hacktoberfest…

What I did

At first, I helped my friend build his open-source project. I introduced him to Hacktoberfest and added issue and PR templates to his project to make it easier for more people to contribute. Project link: https://github.com/TemaDeveloper/library_proj

Then, I found a fun “cat card battle” project on GitHub. I joined it just because it looked interesting - and I love cat pictures. I also noticed that it is a new project created for Hacktoberfest, not too hard, but still meaningful (Not just “add yourself to the Contributors.md”). I contributed code to help the project fetch cat images correctly. Project link: https://github.com/JessieVela/cat-card-battle

My next two PRs were for the OpsiMate project. This project has about 200 stars with a very active open-source community. They even use Slack to make announcements regularly. The reason why I choose this project is after working on two smaller projects, I wanted to join a bigger one that needed more communication and coordination - and OpsiMate was a good match. I unified their eslint and prettier config files, and also helped write some tests. Project link: https://github.com/OpsiMate/OpsiMate

how I’ve progressed

The beginning was difficult. Honestly, the assignment really pushed me to start - because I needed to complete something for the marks. But once I made the first try, I realized most problems were not as hard as I thought.

The hardest part for me was finding the right issues. The hacktoberfest tag and my classmates’ sharing on Teams helped a lot. I also learned a lot about GitHub search. Here’s a document I often used and recommend to others:

https://docs.github.com/en/search-github/github-code-search/understanding-github-code-search-syntax

Then came reading and understanding code - or more exactly, understanding the whole structure of a repository. Usually, a repo has many tools like ESLint, pnpm, biome, etc. These tools may not be part of the main logic, but if they are not configured correctly, the project cannot even run, and there is no way to develop and test the project. I once tried a project that I couldn’t make run locally, and I finally had to give up: **https://github.com/BHChen24/flexprice** (If you are interested, you can give it a try.)

Another important part is using soft skills, like time management and communication. Good time management is important. our professor has told us many times not to push all PRs at the last minute. I tried to make a detailed schedule with flexible options. For example, one week I was sick and couldn’t finish my PR by Friday, but I finished it during the weekend. That was the “acceptable case” in my plan. I also had other priority levels and fallback plans, such as contacting the professor if needed. In longer projects, unexpected things can always happen, so it’s important to track progress and prepare alternatives.

About communication - I noticed many open-source contributors communicate in a very casual way. Maybe that’s a community habit. But some comments like “Hey, give me the issue” feel a bit rude to me. I saw that some people spoke like that and then received no reply 😂. So I try to be polite and neutral, and keep my messages short. Being too formal can also confuse others, I think.

I also learned that timely follow-up is important, because not everyone is a full-time open-source developer. For example, when I was debugging in the cat card project, the author only replied after I mentioned them - so if I had stayed silent, nothing would have moved forward.

What I learned

I think my biggest improvement is getting to know how to read code in a better way. Now, when I start working on a project, I know exactly what to check first: read the README.md, look at the repository’s insights ****tab, read the CONTRIBUTE.md file, etc. I also learned how to use good tools when reading code — I always search first, and then use “go to definition/references” to jump precisely to related code. I scroll much less with my mouse now.

I also became more confident using Git. I use Git often in assignments and at my internship, and I’ve learned some useful details. For example, if I publish a branch first and then rebase, the history becomes very messy like spaghetti - and everyone can see it. But if I don’t publish before rebasing, the worst thing is just a local conflict, which I can solve privately. Then when I publish, the history looks clean and is easier for reviewers to follow.

I also gained inspiration on how to build reliable projects by reading clean repositories, like this one: https://github.com/yamadashy/repomix/

Another repo I liked is https://github.com/juspay/hyperswitch . I didn’t have a chance to contribute yet, but it’s a great example of how to build a financial project in Rust, a direction I’m very interested in. I’ll keep following it.

Considerations

I think I made some progress during Hacktoberfest, but this is still just the beginning.

I had planned to contribute to larger projects (with maybe over 2k stars), but due to time, strange build errors, and some unexpected competition, I chose a safer way to meet the requirements of the course first. Still, I really want to contribute to big projects. Some of my classmates have already done that, and after this round of Hacktoberfest, I finally feel confident enough to try it too in the future.

By the way… seeing my avatar appear in the Contributors list makes me feel kind of proud.

🔔 Prelude: We ****need to be tested for sure

In release 0.2 week 4…

What I did

This week I contributed in another issue in the project OpsiMate, - the same one I contributed to last week.

My main task was to add test cases for one of the APIs.

Working on (issue/PR)

Here’s the issue I picked up: https://github.com/OpsiMate/OpsiMate/issues/371

And here’s my pull request: https://github.com/OpsiMate/OpsiMate/pull/537

This issue was a bit of a “legacy” one. Someone had tried working on it before, but their PR was rejected. Another contributor also took it but later unassigned themselves.

When I saw it sitting there for a while, I thought “Why not give it a try?” So I volunteered to take it on. Right now, both the issue and my PR are still waiting for review.

Need to know

The issue focused on writing tests using the Supertest framework, which is quite similar to Vitest. By looking at existing tests in the project, I quickly figured out how to use it.

It was also very helpful to check some closed issues and PRs - there are lots of good examples there.

Difficulties & Fixes

While testing, I actually found a few bugs in the original API code.

It seems the API didn’t have proper try-catch logic, so it couldn’t return the correct response status. Because of that, I had to mention this problem in my PR - basically saying, “Hey, this API might have a bug. It should be fixed before we can finalize the tests.”

I submitted a draft PR temporarily. The maintainers might ask me to fix the bug as well, or maybe just provide more guidance on the tests. Either way, I just need to wait for the review.

Considerations

I’ve seen some test code that doesn’t really “test” anything - it just exists to make the tests pass.

With AI tools becoming more common in development, this problem might get even more serious: AI can help you generate tests quickly, but those tests might only aim to pass instead of really verifying quality (especially when you tell the AI, “Hey, this code doesn’t work!”).

In my experience, my tests did help me discover real issues and hidden bugs, which shows how valuable testing can be - even if it’s sometimes tedious.

Combining AI-assisted coding with good testing practices is definitely an interesting topic worth exploring in the future.

The feature

I implemented the token counting feature inspired by the Repomix project in this lab.

The feature displays the token cost calculated by a specific model align with each file in the file tree. Users can better manage API call budget now. For example:

I also added corresponding tests to ensure reliability.

The development

In the development step, I tried to apply the TDD pattern

To follow it, I wrote the tests first with AI assistance. Tests provided a clear direction for developing, though some tests turned out to be tricky or hard to satisfy (because they are generated by AI… A strict tech leader!)

In the end, I still have to ask AI for help or frequently search my question online… But I think this experience is valuable.

The inspiration

• Directly referring the pattern for applying tiktoken library in Repomix:
  • this.encoding = get_encoding(encodingName); → tke, err := tiktoken.GetEncoding(encoding)
• Writing test to make the feature more robust (just like what Repomix has done)
• The difference, which is also the challenge, is passing text into the new function and handling the output. Due to the project structure, this is totally different from Repomix so I have to review my code again and try to find a best way to integrate the function into my project
  • Then I noticed that I need to do more refactoring work later.

Next step

I want to add more tests for all features in the project. Also, there are more and more lines piling up in the core.go so I may have to refactor most of the code in it (blame the past me) by wrapping more logic into functions.

Other Interesting things..

CodeRabbitAI gave a wrong suggestion for code changing that broke my CI/CD pipeline! (Do not trust AI so hard…)

🔔 Prelude: If I cannot understand the project, how can I write my own code?

Main Content

Introduction of the target feature

The feature I focused on is token counting. This component is responsible for calculating how many tokens a given text input contains.

I ran the **repomix** project locally and got output like below:

Which I think it’s exactly the feature I need for controlling the cost of calling LLM APIs.

Explore the codebase

To understand the implementation, I went through the official documentation and source code of the project.

• Read the official website – This provided a general overview of what the project does and how it can be used.
• Read the GitHub main page –The project is written in TypeScript, and the main repository offers clear descriptions of the project’s capabilities and setup process.
• Read README.md – This basically is the main content of the GitHub page.
• Read package.json – From here, I learned about the project’s dependencies, scripts, and build process.
• Read CONTRIBUTING.md – This document describes how to develop and contribute to the project. While reading, I also noticed that there is an additional instruction file called repomix-instruction.md, which gives more detailed guidelines.
• Build and run locally – After understanding the setup, I built and executed the project on my local machine to test it directly.
• Locate feature implementations – I identified the files where the token counting logic is implemented by:
  • Ask Claude Code – The project provides a CLAUDE.md file with instructions for AI-assisted development.
• Most important file – The core logic resides in src/core/metrics/TokenCounter.ts. Other related implementations can be found by tracing symbol references from this file.
• Read both the main source code and test files – Doing this helped me understand the internal structure and how the feature is being used in different contexts:

The way to understand the project

One challenge was understanding the tiktoken library.

Originally, tiktoken is a Python package, but this project uses its TypeScript implementation. Since my project uses Go, I had to search for a Go version online. I found pkoukk/tiktoken-go, but after reviewing its issues I discovered that a newer maintained fork exists: localit-io/tiktoken-go. I decided to use the newer one.

While exploring the implementation, I also found some hardcoded parameters in Repomix, which indicate the project’s default behavior (as shown in my screenshots):

It wasn’t very difficult to understand the class pattern in TypeScript, since we have already learned similar concepts in our C++ and Java courses.

I also noticed there are many utility (“util”) functions used throughout the code:

As you can see, except for the line this.encoding = ..., most of the other lines are mainly responsible for:

• setting timers for performance testing
• logging the operations

These parts are not the core logic of token counting; they mainly support it by monitoring and recording runtime behavior.

And, it also has a lot of error handling code:

Being able to identify their purposes can reduce the mental load when reading the code.

Learned

The key to understanding a large codebase is to focus on the core business logic first. Identify which parts handle essential functionality, and which are for error handling, performance monitoring, or utility purposes. While those are important, they are not the main focus for my target feature.

In addition, navigating through references is also very helpful for understanding the codebase. I spent some time learning how to use the “Go to Definition / Type Definition / Implementation / References” features in my editor, and once I got used to them, they saved a lot of time by precisely revealing the details I needed to know.

🔔 Prelude: I am one part of a group of a hundred developers?!

In release 0.2 week 3…

What I did

This week I participated in the project that was recommended by my classmates: OpsiMate; it’s truly an active open-source project—once I commented on an issue, there was a contributor to reply to me in time.

I also joined their slack channel and found they even have short but regular reports for community growth, which makes me really feel like I am a part of the project.

Working on (issue/PR)

The issue I worked on is: https://github.com/OpsiMate/OpsiMate/issues/517 and this is the related PR for it: https://github.com/OpsiMate/OpsiMate/pull/521

This issue is about adjusting the project’s linting and formatting configurations. Before, there were several config files in different folders, such as the app server folder, the client folder, and the shared package folder. So one of the main contributors wants to create unified base configs for both the linter and the formatter in order to manage them in a standardized way.

Need to know

After analyzing the codebase, I realized that the project is mainly using eslint.config.js/mjs and .prettierrc as the configuration files. S the first thing I need to figure out is how prettier and eslint reads their configs from specific files.

And, obviously, .prettierrc doesn’t support importing or exporting, so I need to find a way to transit config objects within config files.

Difficulties

It’s not so hard to find the online resources and apply them to create a new base config file that is accepted by prettier. But the eslint configs seem to be more complex.

Furthermore, once the eslint configuration is broken, it will spread out to subdomains and eventually lead to a failed CI/CD workflow (I made one mistake and then there were a huge number of red error messages that freaked me out). So I need to take it more carefully and frequently ask for help.

Fixes

To be honest, the fixings are not so special or awesome; I basically just followed online instructions plus a little bit of my personal experience to accomplish this issue. If I made a mistake, the local IDE tools like SonarQube, eslint and prettier plugin would correct me before making changes; besides, this project applied the CodeRabbitAI for GitHub PR reviewing. I got a lot of useful suggestions for improving my bug-fixing code. Everything just looks like it’s running smoothly and under control.

Considerations

There are a few interesting thoughts I want to mention here but, I don’t know if I should write some super long paragraphs for each of those 😂, so I decide to list them below as bullet points:

• Technically speaking, this is my first time participating in a project that has a public developing community; my first PR was made for my friend, and my second PR was made for a hacktoberfest-specific project (I think. But it still is a fun project!). So I am very exciting for this week’s work.
• Eslint9 doesn’t support extend syntax anymore, but my work was based on a previous version, so I did pay for it with some useless effort. Thankfully I noticed this problem from the code reviewer. Should take more care about the version of developing tools next time.
• Slack seems super useful for communication. It also likes the discord… Maybe I should take some time to learn about it.
• Do not feel afraid of following up on the work. Eventually we should push the process somehow.

🔔 Prelude: Shall we have a talk about the strange issues?

In release 0.2 week 2…

What I did

This week I mainly worked on a small but interesting project: Cat Card battle (https://github.com/JessieVela/cat-card-battle). It’s a web-based game built with Vue and TypeScript, and styled using Tailwind CSS.

Working on (issue/PR)

Early this week, I found a bug that caused some image URLs from The Cat API to redirect to Tumblr’s “content violation” placeholder instead of showing actual cat photos. Like this:

(Also see: https://github.com/JessieVela/cat-card-battle/issues/23)

So I decided to file this bug as an issue, and see if I can be assigned then fix it.

Need to know

I have some experience with the Vue framework, but I needed to review a few of its concepts. Fortunately, the bug didn’t require any functional changes, so I could focus purely on TypeScript logic.

The next thing I needed was to understand how to use The Cat API. Luckily, they provide detailed documentation:

https://developers.thecatapi.com/view-account/ylX4blBYT9FaoVd6OhvR?report=bOoHBz-8t

Difficulties

The main challenge this week was Tumblr’s redirection behavior.

I used the Network tab in DevTools to trace why placeholder images were being returned and where they came from. Eventually, I found that some image requests returned a 301 status code, with a Location header pointing to a placeholder image.

To handle this, I added logic to detect 301 responses and fetch the image again. But strangely, even after refetching, the placeholder problem was still there. This make me wonder that whether I should dig deeper into Tumblr’s API mechanism — though that might have been too complex.

I finally decided that the issue was likely on The Cat API’s side, and it wasn’t worth pursuing further.

Fixes

For the Tumblr image issue, I implemented a simple workaround: temporarily filter out Tumblr-sourced images. If an image source is detected to be from Tumblr, the app simply re-fetches until it gets the required number of images.

Now, all images come from CDN sources, which should theoretically be more stable.

Another challenge was communication.

After submitting the issue, the repository owner didn’t respond, but they did close another issue during that time. I feel a little bit confused about that but also not sure if I should follow up with them.

Since I already submitted a PR, I decided to wait for a while and may reach out to them proactively if there’s still no reply.

Considerations

While handling the Tumblr image issue in the PR, I felt a lot of pain — every attempt to “check and re-fetch” still resulted in placeholder images. Then I realized something: if the goal is simply to solve the problem, a simpler solution works just as well — the source is unreliable, then I can just don’t use it.

Perhaps in practice, solving a problem doesn’t always require overthinking — sometimes the simplest solution is still effective.

🔔 Prelude: Even more powerful commands for version control

Main Content

Write a blog post about the process of refactoring your code.

• What did you focus on in your improvements? How did you fix your code so it would be better in each step?
• How did your interactive rebase go? Did you find any bugs in your code while you did this? Did you break your program while changing things?
• How did it go using Git to change your project’s history?

What did you focus on in your improvements?

I mainly focused on looking for big code blocks to implement my improvements because it has a higher chance of discovering a function that can be exacted. At the same time, I was also looking for a chance to rename some vague variables and add comments to logic.

I used a code quality checking plugin called SonarQube (https://www.sonarsource.com/products/sonarlint/) to find potential issues in my code. Here is the showcase:

As you can see, SonarQube lists its concerns for my codebase. It’s convenient, but if you are also using Go for programming, you must have noticed that: if err != nil is basically inevitable, counting it into the complexity value is meaningless. It’s still a good tool for pre-checking our code though.

How did your interactive rebase go?

Interactive rebase is surprisingly good, plus I found that GitLens (https://www.gitkraken.com/gitlens) provides a pretty UI with the IDE like VS Code.

(Reference: https://www.gitkraken.com/learn/git/problems/git-interactive-rebase)

I don’t need to be too concerned about the looking of the submit tree now because I learned how to rearrange it by “rebase.” Separately creating small commits also makes the workflow clearer when we are developing. But since it will break the branch - specifically, drop some commit histories - we should always use it on our own, personal topic branch (and we’d better know what we are exactly doing).

Since I only made minor changes, I didn’t confront big issues in this lab, but I do have a story to tell in the next section.

How did it go using Git to change your project’s history?

Here is the concise story of using Git in my lab 5:

• I created new branch
• I made changes
• Too smoothly! I finished all 3 targets without making a commit!
• Had to pick the file that need to be committed, and saved others for later commits… Used add
• In the middle of the way, noticed that the names of the local branch and the remote were different! Had to change them… (Then I deleted the remote one first, I don’t know why I did that.)
• Rebase but failed! Since Git couldn’t find the remote branch…
• …

Well you see, even though I finally managed to rebase my branch, the most difficult part still wasn’t applying some Git commands but driving Git well from the very beginning. However, I got to know at least one thing: Git has most of the methods to help you keep the code history safe and operable (again, if you know what you’re doing there).

I feel like I only touched 30%~40% of Git’s usages. It’s definitely worth investing time to learn it well.

🔔 Prelude: Everything’s hard in the beginning

In release 0.2 week 1…

What I did

This week I mainly focused on searching for suitable open source projects to contribute to. I haven’t started submitting any pull requests yet, but I did managed to create an issue (see link below) and am waiting for it to be assigned.

https://github.com/TemaDeveloper/library_proj/issues/17

Working on (issue/PR)

I opened an issue about setting up issue templates for a repository. Although I think it was a simple one, it still was my first time dealing with this topic, so I referred to the official GitHub documentation. I surprisingly learned that using a .yml file for the issue template allows better formatting and a cleaner layout for users filling in issue forms than the .md template.

The process has been updated; please have a check on the “Updated” section in this post

Need to know

Still waiting for feedback or assignment on my issue. Once that’s done, I plan to contribute my first PR to this project or one of the other candidates I’ve found.

Difficulties

The main challenge this week was finding the right project to start with. Some repositories are attractive and popular but have too many contributors already. It’s so hard to find available “good first issues.” in those repos.

Fixes

After rewatching a previously recorded lecture, I realized I had overlooked GitHub’s advanced search feature. By also researching on the GitHub official documentation, I improved my efficiency in locating suitable issues by using no:assignee, etc. I’ve already starred several projects for upcoming work.

Considerations

Some classmates shared potential projects on our team channel, and I found that exchanging ideas and experiences is really helpful. I believe active communication and collaboration will be key to achieving our release goals.

Updated

I have added templates to the repo and The PR has been merged.

https://github.com/TemaDeveloper/library_proj/pull/18

Here are some things I want to share:

1. Even though this PR is simple, it is somehow a little bit tricky. Because the templates will not be applied until the PR has been merged into the main repo (Github needs to read them), I have to create a new test repository in my account to test the templates.
2. And, this testing procedure did cause a bug: I mistakenly placed the templates in .github/workflow/ISSUE_TEMPLATES instead of the correct path .github/ISSUE_TEMPLATES in the original repo. However, in my separated test repo, the path is correct so that it didn’t reflect any issue.
3. So after noticing the PR has been merged and the bug appeared, I still need to communicate with the owner to let him know I will create a new PR to fix the minor bug (https://github.com/TemaDeveloper/library_proj/pull/19). This cost extra time.

This little issue got me thinking about how to handle PRs whose results only show after merging… I’d like to explore this topic further.

🔔 Prelude: PR, code review and communication.

Refelction

First, how did the code itself go?

The Python project I worked with is clean and straightforward. It made me reconsider my tech stack: I may use Python as my primary prototyping language, and only turn to Go, Rust, or C++ when specific requirements demand it.

Did you run into any problems?

Implementing the logic was simple, but writing tests was more difficult. Too many cases could be included!

How did you tackle the work?

I looked up examples online and used some tools to inspire different test cases.

Second, how did it go using git?

Since I’ve been using Git continuously in recent months, I didn’t face major technical issues. The only recurring problem was occasionally forgetting to create a new branch, etc.

Did you find any of it difficult? How did you get around this?

There was a tricky issue: I directly worked on my forked main branch and mentioned the original issue in one of the commit, so, the issue pointed back to my commit on the main branch. It’s a little bit confused because for a new feature I should have a clearly named branch links to the issue.

Luckily, I could still use the correct branch for making the new PR, but the comments are still left in the issue… And I feel like it’s troublesome to change the recorded behavior on Github.

I haven’t found a perfect solution for human-caused fault yet, so I simply try to be more careful. Fortunately, Git and GitHub are well-designed, so there’s usually a way to recover mistakes.

What would you do differently next time? What did you learn from the experience?

In this week’s lab, a couple of tests passed locally but failed on the maintainer’s machine, so weird. I later realized that the issue was due to a mismatch between my local and pushed code.

Through communication we resolved it, but next time I will double-check my final code version. I also learned that consistent CI/CD pipelines and active communication are essential for online code contributing.

🔔 Prelude: Made a lot of mistakes, yet the actual merging process is very smoothly.

Main Content

Project repo: https://github.com/BHChen24/repo2context

Your issues:

https://github.com/BHChen24/repo2context/issues/19

https://github.com/BHChen24/repo2context/issues/20

Your merge commits:

https://github.com/BHChen24/repo2context/commit/c9ae3957f1fa1749659181ba6c0773c1a7c9d0b8

https://github.com/BHChen24/repo2context/commit/4817fc097517a3c6a7daa8bbd7bcd1d02f25e2a3

Reflections:

Discuss what you did, the changes you made for your features, and the process of doing your merges. What problems did you have? What did you learn? What would you do differently next time?

Merging branches

I basically just followed the lab instructions and completed the main assignment, but I need to develop two extra features in separate branches because:

My initial approach was straightforward: create a branch, finish the feature, then make a PR. Since I followed this workflow step-by-step for each feature, I did not encounter any merge conflicts at all.

Later I realized I misunderstood the instructions. I actually need to trigger the merge conflicts by developing features in parallel, and then merging branches back in a line. I managed to develop two more features and did the fast-forward merge and a three-way merge.

Besides, I also filed some issues to reduce the number of function parameters or refine the output format.

Paid more effort due to begin the work so fast.

What I learned

The biggest lesson in this lab was not about the merges themselves but the importance of carefully reading instructions before diving in.

On the positive side of the first two issues (totally no conflicts but not align with the requirement), I confirmed that my personal development process could be good-for-work: open an issue, create a branch, link the issue to the branch commit (using GitHub keywords like fixes #num), then develop step by step.

For solo development this procedure keeps conflicts to a minimum. I will still follow these steps next time.

However, in a collaborative environment, I think the conflicts are inevitable. That makes it essential to understand Git commands deeply and to take advantage of the rich ecosystem of version control tools.

(I also think that so many tools exist is proof that developers have been tortured by merge conflicts for years…)

CodeRabbitAI code review

Surprisingly, I discovered an auto-review tool while I was looking through examples of “how to file a good issue” on open-source projects.

What impressed me most was that tools like CodeRabbitAI can automatically generate a pull request summary, provide next-step suggestions, and even create sequence diagrams based on the code changes in the PR：

The whole report can be auto-generated and triggered by the work-in-process PR!

Here is an example I explored: https://github.com/BHChen24/repo2context/pull/25

🔔 Prelude: This is my first step into building an open‑source style CLI tool in Go.

Release 0.1

Project Description

For this assignment, I built a “Repository Context Packager” tool named repo2context, which can scan a local git repository and generate a single, well-structured text file with repository information optimized for sending to LLMs such as ChatGPT and Gemini.

Technology Choice

• Language: Go (Golang)
• Output format: Markdown
• Why Go?: Although many people are talking about Go’s advantages all the time, my main reason to do this was simply that I wanted to challenge myself.

Implemented Features

Required Features

• Basic CLI interface with --help and --version
• Repository/file analysis
• Path tree structure
• Git commit/branch metadata
• Summary statistics (file count, lines of code)
• Standard streams (stdout for output, stderr for errors)
• Error handling

Optional Features Implemented

1. Gitignore Integration
   • The tool automatically excludes files and directories listed in .gitignore.
   • Provide a --no-gitignore to disable .gitignore filtering
2. Output to File (-o / --output)

   • Users can save the formatted repository context into a file (markdown text).

   • Example:

     toolname . --output context.md
     # usually the toolname is "r2c" but can be built as other names
     

Development Experience

Process

1. Set up GitHub repository
2. Implement CLI argument parsing in Go (with cobra package)
3. Add recursive directory/file reading; Implement project structure tree displaying; tests…
4. Extract Git info (os/exec to run git commands and parse metadata)
5. Get data together and format output
6. Implement the two optional features: .gitignore handling + output to file
7. Also invite classmates to file issues

Challenges

• Git env: Needed to handle different situations like Git may not be available or the repo may not be initialized. (To be honest, I found this type of check should be applied to basically everywhere, and that’s a bit painful handling errors in Go..)
• Starting from scratch: This was my first time writing a full CLI tool in Go, so I had to set up everything from zero — project structure, flags, Git integration, error handling, etc. (Have to do a lot of research)

Learnings

• Learned how to build a demo project from 0 to 0.1 in Go.
• Gained experience reading Git metadata and filtering files dynamically.
• Deepened understanding of how to do file system traversal, file I/O and error handling in Go.

Summary

• Implemented all required features
• Completed 2 optional features
• A not bad foundation for future extensions
• Good start for practicing open-source contribution process

Links

• GitHub Repository: https://github.com/BHChen24/repo2context/

🔔 Prelude: About the process of contributing a code change to another project

🖋️ Main Content

The project repo: https://github.com/RiverDave/rust-cli-tool

Your issue: https://github.com/RiverDave/rust-cli-tool/issues/27

Your pull request: https://github.com/RiverDave/rust-cli-tool/pull/28

1. What I did

Briefly speaking, I did:

• First take a look at the whole project to see the current situation
• Check if the “recent file” feature has been implemented
• Analyze code base to see how to add custom commands
• Search online for obtaining file metadata in certain language
• Raise issue, fork repo, switch branch, develop logics
• Test my code
• Update documentation
• Create PR
• Communicate with repo owner
• Close issue
• Write blog

1.1 The changes I made for my feature

• I found the rust project used clap — a famous and solid Command Line Argument Parser for Rust.

• Thanks for that, I have a very clear pattern to follow then create a new command for the application:

  #[arg(long = "recent")]
  pub recent: bool,
  

  As simple as it looks like!

• Then, I extended the Config struct to include a recent_only field, which controls whether to filter for recent files.

• Next, I create useful logics in the file.rs. The main filtering logic checks if files were modified within the last 7 days — if a file is older than 7 days, it gets skipped.

1.2 The process of getting your work accepted

• First, review the codebase and existing issues to make sure I understand the basics of the project and avoid raising a duplicate issue.
• Then, communicate with the repo owner — by Teams, by issue, by email, or whatever I like (but also must check the comfortable way for the owner first), to say, “hi, can I add a feature to your project, because…” The core of this is to “let them know.”
• During the coding process, we’ll mainly communicate by the issue. I code, they give feedback, I change my code until we are all good for the issue.

2. Technical aspects

2.1 How did file timestamps work in the language you were working with?

https://doc.rust-lang.org/std/fs/struct.Metadata.html#method.modified

According to this file metadata documentation, we have a lot of tools for obtaining info of a file, including the timestamps for the last modified time. Noticed that this method may “not be available on all platforms” so I added some error-handling code to it.

Next, we should also obtain the current system time (https://doc.rust-lang.org/std/time/struct.SystemTime.html#method.now), minus 7 days, then compare these two variables. If the file wasn’t touched in 7 days, it is not a “recent” file.

2.2 What challenges did you face integrating with the existing codebase?

I think there is one main challenge I want to mention: It takes time to understand the project.

I had to trace through the code to see how clap handles commands. Well… Actually I noticed soon that if I follow the coding pattern in the repo then I should be OK to write the new code. Fully understanding the clap is a hard task itself.

And I also need to figure out how the Config struct flows through the application (The really important task) and where the file processing logic lives in file.rs. Reading other people’s code is always slower than writing your own, plus you have to spend a lot of time researching the language that you are not so familiar with.

2.3 In addition…

In the process of collaboration, I do have a question I really want to ask: Should I use AI tools to quickly understand other people’s open-source projects?

Theoretically, feeding an open-source project into an AI shouldn’t pose security or legal issues, because it’s “open-source”; but, the AI technology is still so new (and the legal issues are always tricky) that no one really knows what the hidden costs might be. Even if I let the AI summarize someone else’s project, who can tell if its summary is reliable?

On the other hand, if I try to research and interpret things completely on my own, there’s still a high chance that I’ll make human mistakes. So, whether or not to use AI tools ends up becoming more of a “trade-off” decision to me…

2.4 How did you handle edge cases?

There was an interesting thing I want to mention in testing. So when I implemented my feature and first tested it, I found that the app would output all the files in the target folder, which made me confused. But later I noticed that because:

1. The target folder for testing is one of this project’s folders.
2. When I use git clone to clone the repo to a local place, it also means that I “modified” all the local files in the folder.

So, the “recent” feature will not filter anything out because all the files are “recently” edited. I think this case can be considered an edge case.

My solution is to manually create a recent_test_files folder that contains some old files and some new files, then test the feature on them. This leads to a correct test result and also prevents the application from reading too many unnecessary files at once.

3. If your repo received a pull request…

Haven’t got a PR yet. 😶‍🌫️

🔔 Prelude: Doing cool things with classmates

• How did you go about doing your code reviews? Do you prefer an async or sync approach? Why?

I prefer the async approach to doing the code reviews; it gives me a flexible schedule to handle my work and life. And I feel relaxed when I need to read something alone.

• What was it like testing and reviewing someone else’s code? Did you run into any problems? Did anything surprise you?

Just like learning new concepts! I may know about the programming language, but the ideas from others are always new and valuable to me. I sometimes could not understand the meaning of others’ code, but thankfully, except for directly asking them, we can also leverage AI in these days.

• What was it like having someone test and review your code? Were you surprised by anything?

It’s just like being judged … but I considered it a little bit; in an open-source community, being reviewed by someone is for making the product better, and then I got relief with this thought. The collaborators always surprise me by discovering new bugs and applying new tests in a way that I never thought of before!

• What kind of issues came up in your testing and review? Discuss a few of them in detail.

Well, for example, I got stuck in the middle when I tried to write tests for a C++ project (although I found that I don’t need to actually write them for this lab in the end). It doesn’t mean I don’t know about C++, but I need time to remind myself of how to write tests in C++ because it has been a while since I used C++ to build something. I have to search online for how to write the tests properly and look for examples. When I face some unfamiliar frameworks, testing and review take time.

• Provide links to issues you filed, and summarize what you found

https://github.com/ElshadHu/RepositoryContextManager/issues/3

This is a tricky one because I am not so familiar with CMakefile. When I tried to build the project the system kept showing errors, I had no idea at that time. But I finally found that it was triggered by the hardcoded PATH setting when I truly dove into the file. I want to tell myself, “If you want to fix a bug, don’t just stare at the error prompts, you have to dive into the file!”

All issues I filed should be under the same issues page; here is another repo I filed issues for: https://github.com/RiverDave/rust-cli-tool/issues

• Provide links to issues that were filed on your repo, and what they were about

https://github.com/BHChen24/repo2context/issues/1

And all other issues are under the “issues” page.

I noticed I included a configuration management tool in my project but since I haven’t used it, I didn’t write any comment or mention it in my “README.md”, and this did cause some confusion. Thanks a lot David!

• Were you able to fix all your issues? What was that like?

https://github.com/BHChen24/repo2context/issues/4

For documentation issues, I can, but for some feature requirements and tricky bugs I cannot yet. Actually, I fixed the markdown file syntax error immediately: the embedding link [https://go.dev/](GO) should be like [Go](https://go.dev/) .(And this is the first time I asked copilot to review my code for the PR, wow!)

• What did you learn through the process of doing the testing and reviewing?

It’s definitely a necessary process for improving our products. The key point here is barely anyone can accomplish a high-quality project by working totally alone. In ancient China there is an idiom: “When everybody adds fuel, the flames rise high,” which means, “Great things can be achieved by mass effort.” This is a wonderful description of the meaning of testing and reviewing in the open-source community.

Yes, I am taking the OSD600 course. To be honest, I have been very eager to take this course because many of my friends told me how valuable it is, and I have already felt the power of the open‑source community — I use Linux daily, I hear stories about open‑source projects and people all the time. In addition, I had never really thought too much about how open‑source projects can influence a company’s business before our first OSD600 lecture; that lecture really caught my interest.

I want to be someone who can confidently say “I am able to develop software for real‑world use” after this term, with open‑source contributing experience. I am especially interested in contributing to projects in the finance field, such as high‑precision computation, trading systems, backtesting systems, and so on.

I researched a project on the daily trend page called “everyone-can-use-english.” [https://github.com/ZuodaoTech/everyone-can-use-english/tree/main] Since English is my second language, I often feel I am not good enough at using it. This project provides a way to improve my spoken English by correcting tone and pronunciation. For example, it has a feature called “Pronunciation Assessment,” which allows me to record my speaking and get feedback on whether it is correct, or how it can be improved.

I also noticed that its documentation is not very complete yet, and currently they only provide some demos in Chinese. Maybe these could be potential entry points for making contributions.