Finding the Right Repository

The first couple of weeks of Hacktoberfest were challenging as I spent a significant amount of time searching for the right repository to contribute to. The competition for beginner-friendly issues was fierce, and many repositories existed solely to allow people to make low-effort pull requests (PRs), which wasn’t the kind of contribution I wanted to make. Eventually, I found a suitable repo: tldr by tldr-pages.

tldr-pages / tldr

📚 Collaborative cheatsheets for console commands

What is tldr-pages?

The tldr-pages project is a collection of community-maintained help pages for command-line tools, that aims to be a simpler, more approachable complement to traditional man pages.

Maybe you're new to the command-line world? Perhaps you're just a little rusty or can't always recall the arguments for commands like lsof, or tar?

It certainly doesn't help that, in the past, the first option explained in man tar was:

$ man tar
...
-b blocksize
   Specify the block size, in 512-byte records, for tape drive I/O.
   As a rule, this argument is only needed when reading from or writing to tape drives,
   and usually not even then as the default block size of 20 records (10240 bytes) is very common.
...

There seems to be room for simpler help pages, focused on practical examples. How about:

This repository is just that: an ever-growing collection of examples…

View on GitHub

The tldr-pages project is a community-maintained collection of simplified help pages for command-line tools. It serves as a more approachable alternative to traditional man pages, making it easier for users to find and understand examples for common commands. Given its active maintenance and practical relevance, it seemed like a great project to contribute to.

The Issue: Adding npm-doctor Command

The tldr repository had an open issue to document various npm commands, and I decided to contribute by working on the npm doctor command. This command checks the health of the npm environment, which is particularly useful for developers troubleshooting their setup.

Let's document: npm #14000

bharateshwq posted on Oct 05, 2024

Command description

This is widely used in development and most of its options are misused or never really used this would be a great contendor

Documentation

https://docs.npmjs.com/cli/commands

Platform

Linux

VCS repository link (e.g. GitHub, GitLab)

https://github.com/npm/cli

Additional information

https://docs.npmjs.com/cli/xxx https://docs.npmjs.com/cli/v10/commands

Commands

• [x] npm 0a4c0f0a3705dae2a8c6d4f9f93d14f57ac6ba7b
• [ ] npm access
• [ ] npm adduser
• [ ] npm audit
• [ ] npm bugs
• [ ] npm cache
• [ ] npm ci
• [ ] npm completion
• [ ] npm config
• [ ] npm dedupe
• [ ] npm deprecate
• [ ] npm diff
• [ ] npm dist-tag
• [ ] npm docs
• [x] npm doctor #14262
• [ ] npm edit
• [ ] npm exec
• [ ] npm explain
• [ ] npm explore
• [ ] npm find-dupes
• [x] npm fund #8495
• [ ] npm help
• [ ] npm help-search
• [ ] npm hook
• [ ] npm init
• [ ] npm install
• [ ] npm install-ci-test
• [ ] npm install-test
• [ ] npm link
• [ ] npm login
• [ ] npm logout
• [ ] npm ls
• [ ] npm org
• [x] npm outdated #14088
• [ ] npm owner
• [ ] npm pack
• [ ] npm ping
• [ ] npm pkg
• [ ] npm prefix
• [ ] npm profile
• [ ] npm prune
• [ ] npm publish
• [x] npm query #8445
• [ ] npm rebuild
• [ ] npm repo
• [x] npm restart #14035
• [ ] npm root
• [x] npm run #14035 (alias of npm run-script)
• [x] npm run-script #14050
• [ ] npm sbom
• [x] npm search #14302
• [ ] npm shrinkwrap
• [ ] npm star
• [ ] npm stars
• [x] npm start #14035
• [x] npm stop #14035
• [ ] npm team
• [x] npm test #14035
• [x] npm token #14250
• [x] npm uninstall #14201
• [x] npm unpublish #14187
• [ ] npm unstar
• [x] npm update #14242
• [ ] npm version
• [x] npm view #14269
• [ ] npm whoami
• [ ] npx

View on GitHub

First, I installed the tldr package on my local machine to get a feel for how it works and to understand the format of the pages. The short explanation and examples it provided were clear and helpful, which encouraged me to contribute to the project.

Preparing the Fix

Before jumping into the code, I followed the recommended steps for contributing to the repository. I checked the contribution guidelines and reviewed previous pull requests to understand how to format my submission according to the project's standards.

Next, I visited the official npm documentation to learn about the npm doctor command in detail. After gathering enough information, I forked and cloned the repository locally, then navigated to the common folder; created a new branch for the change, where I added a new markdown file named npm-doctor.md as per the naming convention for sub-commands.

Here’s what I added to the file:

# npm doctor

> Check the health of the npm environment.
> More information: <https://docs.npmjs.com/cli/commands/npm-doctor>.

- Run all default health checks for npm:
`npm doctor`

- Check the connection to the npm registry:
`npm doctor connection`

- Check the versions of Node.js and npm in use:
`npm doctor versions`

- Check for permissions issues with npm directories and cache:
`npm doctor permissions`

- Validate the cached package files and checksums:
`npm doctor cache`

I made sure the examples were simple, concise, and followed the format used in other tldr-pages. After testing and running required checks on the file locally to ensure everything worked as expected, I was ready to create my PR.

Creating the Pull Request

When creating my PR, I followed the template provided by the repository, which ensured I covered all necessary details. The maintainers were quick to review my submission and requested a few small changes. After addressing their feedback, the PR was merged successfully.

npm-doctor: add page #14262

mayank-Pareek posted on Oct 18, 2024

• [x] The page(s) are in the correct platform directories: common, linux, osx, windows, sunos, android, etc.
• [x] The page(s) have at most 8 examples.
• [x] The page description(s) have links to documentation or a homepage.
• [x] The page(s) follow the content guidelines.
• [x] The page(s) follow the style guide.
• [x] The PR title conforms to the recommended templates.
• Version of the command being documented (if known):

View on GitHub

Challenges & Learning

While this PR was relatively straightforward, mostly consisting of markdown edits, it was a great introduction to contributing to large open-source projects. The main challenge I faced was familiarizing myself with the contribution process of the project. Reading through the repository's contribution guidelines and studying previous PRs helped me understand how to format my submission correctly.

I learned that it’s essential to have a good high-level understanding of the project before starting work and reading other PRs is a good way to learn the methods of contribution. I believe that while my PR was small, it was a good starting point and it gave me insight into how to contribute to large open source projects.

Now that I’ve successfully completed my first PR, I plan to gradually increase the complexity of my contributions. My next goal is to find a slightly more challenging issue, possibly involving code or a bug fix. I’ll continue to document my progress in future blog posts.