Uday RanaLast week I made my first contribution to a large open source project as part of the Open Source course I'm taking at Seneca Polytechnic.
I was looking for issues to help with on GitHub and found one that was a simple documentation update. The project, cve-bin-tool, hadn't had its release log updated for the past few releases. I'd been advised to start with something small so I could get used to the process and this seemed like a good place to begin, especially since one of the maintainers said it was a simple copy-paste job. I left a comment on the issue saying I would like to give it a shot and got to work.
CVE Binary Tool Release Notes page hasn't been updated for v3.3 and now v3.4 was just made
#4458
The CVE Binary Tool Release Notes page wasn't updated for v3.3 and now v3.4 has been released.
Steps to reproduce the behavior:
- go to https://cve-bin-tool.readthedocs.io/en/latest/RELEASE.html
- see the last version to be documented is v3.2
Expected behavior: that v3.3 release would have been documented Actual behavior: release notes are missing for v3.3 ( and please also add in v3.4 now)
N/A
I was asked to do some v3.4r* preliminary testing and found the options/parameters were changed since v3.3 so please make sure when the documentation is updated for 3.4 that the change in parameter/options for the tool command are documented and also the fact that with the move to *.json triage files -previous users can just copy their *.vex triage file to *.json and it will work. Thanks so much!
At first, I forgot to read the CONTRIBUTING.md file. I went straight to the markdown file the docs were generated from, and to their documentation site, which was hosted on Read the Docs. On the website, I saw an option to host my own docs from a GitHub repository, which I thought would be a good way to preview my changes. I forked the repository, cloned it, and deployed my own copy of the docs to test out my changes. I did get around to reading the CONTRIBUTING.md file before creating my pull request, and according to it there's supposed to be a way to build and preview the docs locally but the docs failed to build when I tried so I decided to stick with my original approach since it worked just fine.
Since the maintainer mentioned it was a copy-paste job, I went looking for the existing release notes. I figured the first place to look would be the releases on GitHub and found them right away. I did make some adjustments such as removing the GitHub changelogs and any references to them, since the previous release notes didn't include them, although I did notice the previous release notes didn't bother to remove any mentions of the changelogs even though they're absent from the docs. The markdown file was also inconsistently formatted, and links in the GitHub release notes were missing from the ones in the docs.
Nevertheless, I figured I should ensure my contribution maintains a high standard, so I used markdownlint for my additions and made sure to move any links over, especially since many of them linked to contributors' GitHub profiles. One of the releases also didn't have any notes at all, but I couldn't just remove it. I also couldn't just have a heading with no body. This release was a release candidate for a minor version and there were several others like it with brief release notes simply stating that they were pre-release builds for the next minor version, so I copied the same format.
I then created my pull request, but the continuous integration failed because they had a spell checker which failed on some words not in the dictionary, like GitHub usernames. I was asked to add these to the spell-checker allow-list. I accidentally added them to the wrong file and pushed the change to GitHub. No big deal, I thought. I'd been reading up on git commands like revert and rebase, so I figured it would be an easy fix. I tried doing a git revert and then squashing the revert into the previous changes to undo them. Turns out you're not supposed to do that because it messes with the git history which defeats the entire point of git revert. After repeatedly trying but not being able to get the history to look how I wanted, at some point I got tired and accidentally squashed my commits with somebody else's, and for some reason pushed to GitHub.
While trying to fix my mess, I learned about git reflog, which is a really cool feature which records all updates to the tips of branches in your local repository, including resets and rebases. Despite this, I could not figure out how to solve my problem. I asked my professor for help, who ended up saving me by reminding me I could use git checkout to restore an old commit. I was able to clean up my mess by resetting to the point my branch was created, restoring my changes using the commit SHA from the reflog, and then force pushing my changes to GitHub. I took the scenic route, but managed to get my changes done with a clean git history.
docs: add missing release notes to RELEASE.md
#4464
Fixes #4458. I removed the GitHub changelogs and any references to them, since the notes for the previous releases don't include them. I also added a brief release note for release 3.4rc3 which didn't have one. Please let me know if you'd like anything changed.
After that whole nightmare the spell-checker CI was still failing, which was not a good sign. Luckily, one of the maintainers commented on my PR noting the CI wasn't failing because of the spell-checker but rather because of a bug where it would seemingly abort for no reason. It was able to pass after a re-run and my changes were merged, and that was my first open source contribution. I ended up learning a lot about git because of my mistake, and even though it was stressful, I came out the other side better equipped with the knowledge to deal with messes like this in the future.
(PS: Technically this isn't my first open source contribution - the actual first was to the course notes for another course called Web Programming Principles, and in this course, to the course repository itself, but that doesn't make for as interesting of a title)
