Day 8: The Mirror of Perfection

The Reflecting Hall

On the eighth day, the Keeper of the Repos leads you to the Reflecting Hall, a vast chamber where walls of enchanted mirrors stretch endlessly. These mirrors shimmer with a magical glow, revealing not just the surface of your work but its hidden truths—the clarity of its design, the harmony of its flow, and the shadows of overlooked imperfections.

The Keeper gestures to the mirrors, their voice solemn yet encouraging.

Here lies the power to see what is often missed, to uncover the pathways to refinement and strength. With care and diligence, you can ensure that every piece of your craft shines with purpose and excellence.

But beware! The Shadows of Sloppiness linger in these reflections, feeding on neglect and disorder. Only with vigilance and the wisdom of the mirrors can their influence be cast away.

Choose the rune that best suits your skills and experience:

Snowflake Rune: Beginner, you’re starting a new artifact. Go to the beginner challenge.
Snowball Rune: Intermediate, you already have an artifact and want to enhance it. Go to the intermediate challenge.
Ice Rune: Advanced, you already have a large or several artifacts and want to go further. Go to the advanced challenge.

If you’re joining the village today, you can always catch up on the instructions from Day 1 to get up to speed.

Beginner: Add a Code Formatter and a Linter

Snowflake rune
Beginner level for folks starting a new artifact

The Keeper of the Repos stands beside one of the mirrors, its surface shifting like a restless pool of silver. With a wave of their hand, they summon a faint outline—a fractured image, scattered and uneven.

See how the mirror reveals what lies beneath?

The Keeper steps aside, allowing you a closer look.

To bring harmony to this reflection, you must first embrace the tools of order. These ancient instruments, passed through generations of artisans, align even the smallest details with precision.

The Keeper places a small, glowing token in your hand, its surface etched with intricate patterns.

Use this token to guide your craft, smoothing the edges and unifying the form. Each stroke of improvement brings you closer to perfection, a reflection unmarred by chaos.

Code formatters and linters are indispensable tools for ensuring code quality and maintaining a consistent style across your projects. However, while they may seem similar, they serve distinct purposes: a code formatter ensures consistent style (e.g., indentation and line breaks), while a linter catches potential bugs and enforces coding standards (e.g., naming conventions and best practices).

Today’s challenge involves two steps:

Adding a code formatter.
Adding a linter.

From this point onward, the Advent won’t provide step-by-step instructions for every task since tools and configurations vary widely depending on your project’s needs. Instead, we’ll outline general steps to help you get started, but feel free to adapt them and explore further.

Add a code formatter.

Code formatters ensure consistent code style by automatically applying predefined formatting rules. Follow these steps to add one to your project:
1. Choose a code formatter.
  
  Popular choices include Prettier, which supports multiple languages and has flexible configuration options.
2. Install the formatter.
  
  Follow its installation instructions to add it as a development dependency. For example, with Prettier, use a package manager to install it. Refer to the Prettier installation guide.
3. Configure the formatter.
  
  Create a configuration file (e.g., .prettierrc for Prettier) to define the rules for your project. Tailor these rules to match your coding standards.
4. Run the formatter.
  
  Most tools provide commands for checking and fixing formatting issues. For Prettier:
  - npx prettier --check . checks for formatting issues.
  - npx prettier --write . automatically formats the code.
  Run the write command to ensure your codebase is formatted correctly.
5. Install an editor extension.
  
  For example, install the Prettier editor extension to format your code on save.
Add a linter.

Linters focus on catching bugs and enforcing coding standards. The steps are similar to setting up a formatter:
1. Choose a linter.
  
  Tools like ESLint are popular for JavaScript projects. Choose one that fits your project’s needs based on the stack you’re using.
2. Install the linter.
  
  Add it as a development dependency and follow its installation instructions.
3. Configure the linter.
  
  Create a configuration file (e.g., .eslintrc for ESLint) to define the rules. Customize them to meet your project’s requirements.
4. Run the linter.
  
  Use the linter’s CLI to check your codebase for errors and warnings.
5. Install an editor extension.
  
  For ESLint, you can install the ESLint editor extension to display linting issues directly in your editor.

With your formatter and linter configured, you’ve taken a huge step toward maintaining a clean and professional codebase. These tools will help you enforce best practices and ensure that your project remains consistent and error-free, even as it grows and evolves. Great job on completing this essential challenge!

Success Criteria

✓ A code formatter is set up in your project. It can be run locally.
✓ A linter is set up in your project. It can be run locally.
✓ Both extensions are installed in your code editor.

The mirror now gleams with an unbroken image, its surface smooth and harmonious. The fractured outline has transformed into a vision of balance and clarity, radiating with a gentle light.

The Keeper of the Repos studies the mirror, their expression a mixture of pride and satisfaction.

You have brought unity to your reflection, wielding the tools of order with skill and care. The Shadows of Sloppiness have no place here, for your work now stands as a testament to diligence and mastery.

They gesture toward the hall, where the other mirrors shimmer in approval.

Remember this: the art of refinement is not a single act, but a practice. Return to the mirrors often, and let their wisdom guide you. With each visit, your work will grow stronger, clearer, and ever more enduring.

The hall brightens, the mirrors casting their light into the corners of the chamber. The Keeper bows slightly, their voice filled with quiet encouragement.

Your path is illuminated. Walk it with confidence and grace.

The Keeper’s Insight

Creations that simply function are not enough. In the Reflecting Hall, you will learn to polish your work, refining it to a state of excellence. Only through vigilance and discipline can you banish the Shadows of Sloppiness.

Proceed, traveller, and perfect your craft. Return tomorrow for the next challenge in your journey through the Advent of Open Source.

Intermediate: Automate Code Formatting and Linting With CI

Snowball rune
Intermediate level for folks wanting to enhance an existing artifact

In the dim light of the Reflecting Hall, another mirror draws your attention. Unlike the others, its surface is in constant motion, shimmering as if alive. The Keeper of the Repos approaches with a knowing smile, gesturing toward the restless glass.

This mirror shows a reflection not bound to a single moment. It reveals the ongoing flow of your efforts, capturing each step of progress and every potential stumble.

From their satchel, the Keeper retrieves a delicate hourglass filled with sparkling grains of light.

This is the Hourglass of Flow, a gift from the artisans of the Forge of Productivity. With its magic, your efforts will no longer rely on memory or chance. Every improvement will be checked as it is born, ensuring consistency without hesitation.

They place the hourglass on the edge of the mirror, its glow syncing with the movement of the glass.

Use its power wisely. When the flow is aligned, you will find even the most unruly shadows swept away before they can take root.

The Keeper steps back, nodding for you to begin.

Integrating code formatting and linting into your CI pipeline ensures that every change follows the same formatting and linting rules, reducing the need for manual reviews and improving code quality. This is a crucial step for projects that involve multiple contributors, helping to maintain consistency and catch issues early in the development process.

Today’s challenge will guide you through setting up the automation for both code formatting and linting in your CI pipeline, ensuring that every pull request is thoroughly checked for formatting issues and code quality before it is merged.

Set up code formatting and linting.

Before diving into CI automation, ensure that you have both a code formatter and a linter set up in your project.

For this challenge, we’ll use Prettier (code formatting) and ESLint (linting and code quality checks) as examples. If you’re using different tools, please adapt the steps accordingly.

Check out the Beginner challenge: Add a Code Formatter and a Linter for detailed instructions on setting up Prettier and ESLint in your project.

At this point, you should have something like:
- A configuration file for your code formatter (e.g., .prettierrc for Prettier).
- A configuration file for you linter (e.g., .eslintrc for ESLint).
- Scripts for code formatting and linting issues to check and fix locally your files.
  
  For example, you can have in a package.json file the following scripts to run Prettier and ESLint for checking and fixing issues:
  - format: Runs Prettier to format the code.
  - format:check: Checks the code for code formatting issues.
  - lint: Runs ESLint to check and fix linting issues.
  - lint:check: Checks the code for linting issues.
  package.json
```
{
  "scripts": {
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "lint": "eslint . --fix",
    "lint:check": "eslint . --max-warnings=0"
  }
}
```
Set up GitHub Actions for code formatting and linting.

Now, let’s automate the process in your GitHub Actions workflow. We will create a CI pipeline that runs your code formatter and linter on every pull request.
1. Create or edit the GitHub Actions workflow.
  - In your project, navigate to .github/workflows/.
  - Create a new file called lint.yml or edit an existing workflow file.
2. Define the workflow.
  
  Here’s a sample configuration for a GitHub Actions workflow that checks for code formatting and linting on pull requests with Prettier and ESLint:
  .github/workflows/lint.yml
```
name: Code Quality Check
on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          cache: npm
          node-version: 20

      - name: Install Dependencies
        run: npm install

      - name: Run Prettier Check
        run: npm run format:check

      - name: Run ESLint Check
        run: npm run lint:check
```
  The workflow does the following:
  1. Checks out the code for each pull request.
  2. Sets up the environment (e.g., Node.js).
  3. Installs project dependencies.
  4. Runs the code formatter to check for code formatting issues.
  5. Runs the linter to check for linting issues.
  If any issues are found, the workflow will fail, indicating that the pull request needs further attention.
Test the CI pipeline.

After pushing your changes to GitHub:
1. Open a pull request to your repository containing code formatting or linting issues.
2. The GitHub Actions workflow should run automatically.
3. Check the Actions tab in your repository to see the workflow status.
4. It should fail. Review the logs to identify the issues.
5. Fix the issues locally and push the changes to the pull request branch.
6. The workflow should run again and pass this time.
Encourage contributors to use code formatting and linting locally.

While the CI pipeline ensures that pull requests are checked automatically, encourage your contributors to run the code formatting and linting check and fix commands locally before pushing their changes. This will help them fix any issues beforehand, speeding up the review process.

You can add this recommendation to your project’s CONTRIBUTING file or documentation to help developers adhere to the code quality standards.

By automating code formatting and linting with CI, you’ve streamlined the process of maintaining consistent, high-quality code across your project. This automation ensures that every contributor’s code adheres to the same standards, reducing errors and the need for manual reviews. It’s a great practice for any team or Open Source project to incorporate these tools into the development workflow.

Congratulations on completing this challenge! By implementing code formatting and linting checks in your CI pipeline, you’ve taken a significant step toward improving your project’s code quality and developer productivity. Keep up the great work!

Success Criteria

✓ Code formatting and linting scripts can be used locally.
✓ A GitHub Actions workflow is set up to check code formatting and linting on pull requests.
✓ The CI pipeline runs and successfully checks for code formatting and linting issues.
✓ The workflow fails if formatting or linting issues are detected.

The mirror still ripples, but now with a steady, calming rhythm. Each movement reflects a sequence of harmony, where every step forward is met with a reassuring light. The Hourglass of Flow shines brightly, its grains of light moving in perfect synchrony with the mirror’s dance.

The Keeper of the Repos observes the transformation, their expression one of deep satisfaction.

You have woven the flow into your craft, ensuring that each moment builds upon the last without falter. The Shadows of Sloppiness have no foothold here, for your vigilance now reaches every corner of your efforts.

They retrieve the hourglass, its light dimming slightly as it returns to their satchel.

This tool will serve you well, but it is the habits you’ve built that will endure. With each reflection kept clear, your work will not only remain strong but inspire those who follow to uphold the same discipline.

The Keeper gazes at the mirror one last time, its glow casting warm light across the hall.

Go forth with the confidence of one who masters not only the present but safeguards the path ahead. The Reflecting Hall will always await your return.

The Keeper’s Insight

Creations that simply function are not enough. In the Reflecting Hall, you will learn to polish your work, refining it to a state of excellence. Only through vigilance and discipline can you banish the Shadows of Sloppiness.

Proceed, traveller, and perfect your craft. Return tomorrow for the next challenge in your journey through the Advent of Open Source.

Advanced: Standardize Code Formatting and Linting Across Projects

Ice rune
Advanced level for folks wanting to enhance an existing large artifact or several org/personal artifacts

Near the far end of the Reflecting Hall, you notice a series of mirrors arranged in a precise, repeating pattern. Unlike the others, these mirrors do not focus on a single image but instead echo one another endlessly, their reflections creating a seamless, unified vision. The Keeper of the Repos stands beside them, their gaze steady and contemplative.

These mirrors belong to the Concordant Array,

they explain, their voice calm yet purposeful.

They reveal the power of harmony: when every effort aligns, even across vast distances, the result is something greater than its parts.

The Keeper produces a small, intricately carved scale, its surface inscribed with patterns that shimmer faintly in the light.

This is the Godo, Balancer of Unity. With it, you can ensure that every piece of your craft, no matter where it lies, follows the same guiding principles. In doing so, you eliminate discord and create a foundation that others can trust and build upon.

They place the scale before you, its glow pulsing softly as it awaits your touch.

Step into the Concordant Array, and bring order to what was once scattered.

In any Open Source or collaborative project, ensuring consistency in code formatting and linting is critical. When multiple contributors work on different parts of a project, different repositories linked together, it’s essential that everyone follows the same guidelines. Without a uniform approach, the codebase can quickly become hard to navigate, leading to errors and inefficiencies. By standardizing code formatting and linting across your projects, you ensure that your team follows the same practices, making the code easier to maintain and improving the overall quality of contributions.

Today’s challenge will guide you through creating custom code formatting and linting configurations that can be reused across multiple repositories. This will help you establish consistent coding standards across all your projects. We’ll also explore how to enforce these standards by sharing your configurations and auditing them periodically to ensure that they continue to meet your team’s goals and project needs.

Create a custom code formatter configuration.

The first step is to set up a code formatter configuration that you can reuse to ensure a consistent style across your projects.

For a detailed Prettier step-by-step guide, refer to the Prettier documentation on Sharing Configurations.

Here’s how to create and share your configuration.
1. Create a new repository for the formatter configuration.
  
  Set up a new repository dedicated to your custom code formatter configuration.
2. Inside the repository, create the configuration file. (e.g., .prettierrc for Prettier).
  
  Define the formatting rules that align with your team’s coding standards. Customize the rules to match your project’s requirements.
3. Configure the formatter.
  
  Customize the rules according to your team’s preferences.
4. Publish the configuration.
  
  Initialize your project with the init command of your package manager (e.g., npm init for npm).
  
  Then, publish the configuration to a package registry (e.g., npm publish --access public for npm).
Create a custom linter configuration.

Just like with code formatting, linters can be configured to enforce coding standards across your projects. linter ensures that your code adheres to certain best practices, such as avoiding unused variables, preventing common mistakes, or enforcing consistent naming conventions.

The steps to create and share a custom linter configuration are similar to those for a code formatter.

For detailed ESLint-specific guide, refer to the ESLint documentation on Sharing Configurations.
Use the shared configurations across repositories.

Once your configuration packages are published, the next step is to share them across your repositories to ensure consistent formatting and linting.

For each repository that you want to apply the shared configurations to:
1. Set up the code formatter and linter.
2. Install the code formatter and linter configuration packages that you published earlier.
3. Provide instructions on how to run the code formatter and linter scripts locally in the repository’s contributing guide.
4. Enforce the use of the code formatter and linter in your CI pipeline.
  
  See the Intermediate challenge for guidance on setting up CI checks.
Periodically audit and update the configurations.

As your projects evolve, you may need to update your code formatting and linting rules. Over time, your team’s coding standards may change, or new best practices may emerge. Periodically reviewing and updating your configurations ensures that your codebase remains consistent with the team’s goals.
1. Run an audit: Periodically check your repositories to make sure the formatting and linting configurations are still being followed. This can be done manually or through automated checks in your CI pipeline.
2. Update the configurations: If needed, modify your configuration files and republish the updated versions. Inform your contributors about the updates, and encourage them to install the latest versions of the configuration packages in their projects.

By creating custom, shareable configurations for both code formatting and linting, you’ve established a standardized approach to managing code quality across multiple repositories. This consistency not only improves collaboration but also reduces errors and makes it easier for new contributors to get involved. Periodically reviewing and updating these configurations ensures that your standards evolve with your project’s needs, keeping your codebase clean and maintainable.

Congratulations on completing this challenge! By standardizing your code formatting and linting, you’ve taken a critical step toward building a high-quality, maintainable codebase across all your projects.

Success Criteria

✓ Custom code formatter and linter configuration packages are created and published.
✓ Configuration packages are shared and installed across multiple repositories.
✓ Code formatter and linter configurations are enforced through CI pipeline.
✓ Periodic audits and updates of code formatting and linting rules are scheduled.

As you step back from the Concordant Array, the mirrors shimmer in unison, their reflections now perfectly aligned. The carved scale glows steadily in your hand, its once-shifting patterns now forming a cohesive and harmonious design.

The Keeper of the Repos approaches, their expression filled with quiet pride.

You have achieved what many overlook: the harmony of effort across all realms. With Godo, Balancer of Unity, you’ve ensured that no matter where your work leads, its foundation remains constant, clear, and strong.

They take the scale, its light dimming slightly as they stow it safely within their satchel.

This alignment will ripple outward, inspiring all who contribute to join in the same unified effort. You have not merely brought order to your own craft but created a guide for countless others to follow.

The Keeper gestures toward the mirrors, now glowing with a gentle, reassuring light.

Return to your journey with the knowledge that your path is not just your own. It is a path that others will walk beside you, strengthened by the unity you have forged.

The Keeper’s Insight

Creations that simply function are not enough. In the Reflecting Hall, you will learn to polish your work, refining it to a state of excellence. Only through vigilance and discipline can you banish the Shadows of Sloppiness.

Proceed, traveller, and perfect your craft. Return tomorrow for the next challenge in your journey through the Advent of Open Source.