DEV Community: Yousef

Reflecting on the Journey with Explore.CLI

Yousef — Mon, 11 Dec 2023 22:23:57 +0000

As I close this chapter of my contributions to Explore.CLI, it's time to reflect on the results, the learning process, and the invaluable interactions with the community that shaped this journey.

Achieving Goals and Implementing Technical Features

The primary goal of enhancing the 'Import' feature with the --names option has been successfully achieved. Other goals such as removing deprecated options and bug fixes have also been achieved and the pull request was merged seamlessly, marking a significant milestone. This achievement was not just about adding features. It demonstrated my growth in understanding the project's expectations and improving my testing skills to identify and address bugs proactively.

The technical implementation of this feature was a critical aspect of my contributions to Explore.CLI. The process entailed modifying the Option variable and command handler to make room for the new functionality. Additionally, it was necessary to incorporate logic that could process the provided list of names effectively. I provided more technical details in my previous blog post. The emphasis was on writing clean and efficient code to ensure that these new features integrated seamlessly into the existing framework without disrupting the user experience.

Equally important was the rigorous testing and debugging phase, which went beyond merely verifying successful implementation. It was about ensuring that the introduction of new features did not give rise to new bugs. This step was instrumental in maintaining the integrity and reliability of the tool, reinforcing its value to the users.

Managing Expectations and Time

Reflecting on the goals I had initially set, my ambition was always high. This time, I deliberately chose issues within my capacity, learning from past experiences where I overestimated my bandwidth. Balancing this project with academic responsibilities taught me the importance of time management and setting realistic expectations. This approach of tackling problems incrementally not only made the workload manageable but also boosted my confidence and efficiency.

Learning from the Process and Community Interaction

Throughout this journey, I've encountered a significant learning curve that has been nothing short of transformative. Additionally, the process has refined my coding abilities, particularly in optimizing and cleaning up the codebase. Removing deprecated features while ensuring existing functionalities remain unaffected has taught me the essential practice of maintaining a clean and efficient code structure.

The role of the community surrounding Explore.CLI cannot be overstated. Collaborating with other contributors through GitHub issues and pull requests (and sometimes on other social media apps) proved to be a cornerstone of the problem-solving process. The diverse perspectives and alternative solutions offered by community members often shed light on issues and potential improvements I hadn't previously considered. Moreover, the constant stream of feedback was invaluable for fine-tuning the features I worked on. This two-way exchange allowed me not only to contribute my knowledge but also to benefit from the collective wisdom of the community.

Concluding Thoughts

Looking back, this experience with Explore.CLI has been about growth, technical challenges, and community engagement. It was more than just coding; it was about being part of an ecosystem where each contribution matters. As I move forward, the insights and skills gained from this project will undoubtedly influence my future endeavours in open-source development.

Explore.CLI - Progress

Yousef — Sat, 09 Dec 2023 15:52:57 +0000

Welcome back to the ongoing journey of enhancing Explore.CLI! As I discussed last week, my focus has been on implementing new features and refining existing ones. In this update, I am excited to share the progress made and the intricacies of the latest improvements.

Enhancing the 'Import' Feature

Building upon the momentum of previous weeks, where I enhanced the Export feature, I turned my attention to the Import feature. The primary enhancement was the integration of the --names option, similar to what was done for Export. This required a few key updates:

Modifying the Option variable names to indicate its dual functionality for both import and export.
Adjusting the importSpaceCommand to correctly utilize the names option.
Updating the ImportSpaces method to handle a comma-separated list of names.

The implementation ensures a more intuitive and flexible import process, catering to specific user needs.

Code Refinement and Bug Fixing

In addition to feature enhancement, a significant part of my focus was on refining existing code and addressing bugs:

Removing Deprecated Features: Following discussions on issue #18, I removed the import-inspector-collections feature, ensuring the codebase remains streamlined and up-to-date.
Bug Fixing: A small bug, identified in my previous contributions, was addressed. The application now displays an appropriate message when no matching spaces are found during export or import, improving user experience.

Code Snippets

Here's a glimpse of the key code changes implemented:

Modifying the names option:

var names = new Option<string>(name: "--names", description: "The names of the spaces to export or import") { IsRequired = false };

Adjusting importSpaceCommand:

var importSpacesCommand = new Command("import-spaces")
{
    exploreCookie,
    importFilePath,
    names,
    verbose
};

importSpacesCommand.SetHandler(async (ec, fp, v, n) =>
    { await ImportSpaces(ec, fp, v, n); },
    exploreCookie,
    importFilePath,
    names,
    verbose);

Implementing checks for matching spaces during import and export:

// For Export
if (namesList?.Count > 0 && space.Name != null && !namesList.Contains(space.Name))
{
    AnsiConsole.MarkupLine($"[orange3]'Skipped {space.Name}': Name not found in list of names to export[/]");
    continue;
}
// For Import
    foreach (var exportedSpace in exportedSpaces.ExploreSpaces)
{
    if (namesList?.Count > 0 && exportedSpace.Name != null && !namesList.Contains(exportedSpace.Name)) {
    AnsiConsole.MarkupLine($"[orange3]'Skipped {exportedSpace.Name}': Name not found in list of names to import[/]");
    continue;
    }
}

Documentation and Pull Request

Finally, the README.md file was meticulously updated to reflect these changes, aiding future contributors and users. All these updates are encapsulated in a pull request, which is currently under review. I have already addressed a minor typo pointed out by the repository owner and am eagerly awaiting the final approval.

Conclusion

This phase of enhancements to Explore.CLI has been a blend of expansion, refinement, and learning. It demonstrates the project's commitment to continuous improvement and user-centric development. As always, I am keen to hear feedback and look forward to sharing more updates soon.

Planning More Enhancements for Explore.CLI

Yousef — Fri, 01 Dec 2023 23:50:48 +0000

Introduction to Future Contributions

As I continue my journey with the open-source project Explore.CLI, my focus shifts toward upcoming enhancements and learning from past experiences. Although I recently added new features and identified a minor bug in my previous work, the path ahead promises more growth and development.

Planned Enhancements and Strategy

Expanding the 'Import' Feature

After fruitful discussions with the repository owner, I am set to extend the functionality of the Import option, mirroring the expansion I previously implemented in the Export feature. The main task involves integrating the --names option into the Import functionality.

Removing Deprecated Feature

A significant part of my upcoming work includes removing the now-deprecated import-inspector-collections feature. This task necessitates a detailed review of the codebase to ensure complete and clean removal of all related components, ensuring the application remains efficient and up-to-date.

Addressing Past Bugs

In addition to these enhancements, I plan to rectify the bug identified in my previous contribution. It involves implementing a more accurate user notification system for scenarios where provided Space names do not match, affecting both the Import and Export features with the new changes planned.

Approach and Reflections

Learning and Adapting

Reflecting on my previous experience, where I underestimated the workload, I intend to approach these tasks with a more segmented and manageable strategy. This approach aims to prevent overextension and ensures that each enhancement is given the attention it deserves.

Preparatory Work

Before diving into these tasks, I need to familiarize myself with the intricacies of the Import feature, and understand its functionality, requirements, and code structure. This preparation is crucial for effective and efficient development.

Documentation Updates

An important final step will be to update the README.md file, reflecting the new changes and improvements made to the Explore-CLI project. This documentation will assist future contributors and users in navigating the enhanced application.

Conclusion and Upcoming Update

As I embark on these new challenges and opportunities for growth within the Explore-CLI project, I look forward to sharing insights and progress in my next update. Stay tuned for a detailed account of how these enhancements unfold and the lessons learned along the way.

The NuGet Publishing Puzzle

Yousef — Fri, 24 Nov 2023 19:45:09 +0000

Navigating the Challenges with Learn2Blog

Hello again, readers! Today, I want to share a recent experience that illustrates the complexities and unexpected hurdles in software development. Specifically, my journey in attempting to publish my project, Learn2Blog, to NuGet.

Preparing for NuGet Publication

After weeks of diligent development on Learn2Blog, I reached a point where I was ready to publish it on NuGet. For those unfamiliar, NuGet is a package manager for the Microsoft development platform, and publishing a project on it involves creating a .nupkg file – a packaged version of your project.

Adhering to the NuGet Documentation

To ensure a smooth process, I turned to Microsoft's Package creation workflow in the NuGet Documentation. This section meticulously outlines the necessary steps for packaging a project. The subsequent step involves creating an account on NuGet and uploading the .nupkg file.

Facing the Unexpected

Confidently, I followed the instructions, ensuring my project was correctly set up for packaging. However, when I ran the packaging command, nothing seemed to happen. No .nupkg file was created. Increasing the verbosity with the -v flag in a subsequent attempt, I analyzed the log for errors or warnings, only to find none. My next move was to use the -o flag to specify an output directory, but again, no file was generated.

Exploring Potential Issues

At this point, I began to contemplate various potential issues that might be causing this behaviour. Could there be an unseen error in my project configuration? Was there a problem with the version of the .NET framework I was using? Or perhaps there was an issue with the NuGet package manager itself.

A Stalemate and Further Exploration

Despite exploring every avenue I could think of and scouring the internet for solutions, I found myself at an impasse. In an attempt to uncover some clue or insight, I even delved into other .NET open-source projects, hoping to stumble upon a similar issue or a hint that could lead me in the right direction.

A Temporary Pause

Faced with a persistent mystery and no clear path forward, I decided to step back from the issue, planning to revisit it if I came across any new information or insights. Sometimes, taking a break and returning with a fresh perspective can make all the difference in problem-solving.

Reflecting on the Process

This experience with NuGet and Learn2Blog is a reminder of the intricate and often unpredictable nature of software development. It highlights the importance of resilience, continuous learning, and the willingness to seek help from the community.

Stay tuned for updates on this journey, and in the meantime, I encourage anyone who has faced similar challenges or has insights to share to reach out. Together, we can unravel these puzzles and continue to grow as developers.

Until next time, keep coding and exploring!

Enhancing Explore.CLI

Yousef — Fri, 24 Nov 2023 19:00:03 +0000

Greetings, fellow developers! Today, I'm happy to share my recent adventure with the Explore.Cli project, a journey marked by tackling challenging features and collaborative problem-solving, ultimately leading to the exciting release of Explore.CLI version 0.4.0.

Introduction to Explore.CLI

During Hacktoberfest 2023, I discovered Explore.Cli, an intriguing command-line tool that piqued my curiosity. This tool offers a range of functionalities designed to enhance user experience working with SwaggerHub, sparking my interest to dive deeper and contribute.

Initial Steps and First Contributions

My first engagement with Explore.Cli involved fixing a bug in their export feature, a process I detailed in a blog post you can find here. This initial step marked the beginning of a deeper journey into the project's development.

As I familiarized myself with Explore.Cli, several open issues caught my attention. Despite initial hesitations, I revisited two particular issues, deciding to take on the challenge of resolving them.

Issue #6: Enhancing Export Functionality

The first issue I tackled was issue #6, aimed at adding the ability to specify both a path and a filename for exporting. This required the introduction of a new Option variable:

var exportPath = new Option<string>(
    name: "--export-path", 
    description: "The path for exporting files. It can be either a relative or absolute path")
    { IsRequired = false };
exportPath.AddAlias("-ep");

I also adjusted the Handler for the exportSpacesCommand to integrate this new option:

exportSpacesCommand.SetHandler(async (ec, ep, en, v) =>
    { await ExportSpaces(ec, ep, en, v); },
    exploreCookie,
    exportPath,
    exportName,
    verbose);

Subsequently, the ExportSpaces method was modified to include these new options, and the README.md was updated to reflect these changes, culminating in pull request #13.

Building Upon the Foundation: Issue #4

Next, I addressed issue #4, which involved adding a feature for users to select specific spaces to export. Building on my previous work, I ensured compatibility and consistency by developing this feature on top of the initial issue branch, incorporating all commits from pull request #13 into pull request #14.

Refining and Resolving Challenges

Throughout this process, I encountered various challenges, including aligning my code with the project's coding style, handling additional scenarios, and implementing file system permissions checks. Feedback from the project author prompted significant refinements and improvements, including code refactoring and unit testing.

Workflow and Platform-Specific Considerations

An interesting twist occurred when some of my tests failed on a workflow run. This issue arose due to the GetInvalidFileNameChars() and GetInvalidFilePathChars() methods behaving differently on Linux compared to Windows. Initially, I addressed this by creating a custom array for invalid characters, but I later realized that this was unnecessary, as the project was intended for Windows use. This was a valuable lesson in understanding project scope and platform-specific considerations.

Release of Explore.Cli v0.4.0

Finally, after overcoming these challenges and learning from them, I'm excited to announce that Explore.Cli v0.4.0 is officially out!. This release marks a significant milestone in my open-source journey.

Reflecting on the Experience

This experience with Explore.Cli` has been both challenging and rewarding, reinforcing the collaborative and supportive nature of the open-source community. Each contribution, from code to conversations, has been a valuable part of my growth as a developer.

Stay tuned for more insights and developments, and as always, I encourage you to dive into the project, contribute, and share your expertise. Happy coding!

GitHub Actions Workflow

Yousef — Sat, 18 Nov 2023 01:21:31 +0000

Introduction

In this week's focus on enhancing the development process for Learn2Blog, I delved into the realm of Continuous Integration (CI) by implementing a GitHub Actions Workflow. Continuous Integration pipelines and workflows are pivotal in modern software development, providing automated checks and balances to ensure code quality and stability.

Setting Up the Workflow

To start, I turned to the starter-workflows repository, a valuable resource housing diverse YAML files for various project types. My project being in .NET, I checked out the dotnet.yml file to get insights into the setup process. Understanding the YAML syntax and keywords like on, push, jobs, and steps is crucial for crafting an effective workflow. In my case, I wanted to the workflow to trigger "on" any "pushes" on the main branch. The job describes the specific task which can be given a name, and steps outline the necessary steps to run the job.

You can also go the Actions tab on your main repository page and and select new workflow from the menu on the left hand side. GitHub will recommend some templates for you based on your project. You can always modify it to your specific needs.

Drawing inspiration from another open-source project, explore-cli, I learned how to tailor the workflow to accommodate the nested structure of my tester project. This involved specifying the path to the test .csproj file, a key adjustment for successful execution.

My workflow encompasses several essential steps:

Checking out the latest code from the main branch.
Setting up the .NET environment.
Restoring dependencies (which ensures that the project has all the necessary packages)
Building the application.
Running the test files

For a detailed view of the workflow, refer to the dotnet.yml file.

Hiccups Along the Way

Just when everything seemed to be working fine, an unexpected challenge arose. While the workflow passed when I ran it, a contributor's pull request triggered failures in seemingly unrelated tests. Despite the contributor's newly added test passing, other existing tests failed mysteriously. Investigating this remains something I had to leave behind for the time being and come back to it later, and the pull request is temporarily on hold. But if you know why, please let me know in the comments!

Contributing to Node-TILify

Beyond my project, I also contributed to Node-TILify, a similar project by my friend @sdthaker. Although I have an aversion to JavaScript [cue laugh emoji], he threw me a challenge my way. Testing his workflow seemed like a good gig!

There are of course many differences between Jest and xUnit. I am fairly familiar with Jest as I have worked with it in the past, so setting up a new test for him was not particularly difficult. I would say working with xUnit has actually been more challenging since I am very new to it.

Conclusion

To wrap it up, Continuous Integration (CI) plays a pivotal role in safeguarding code quality and stability. Whether you're an external contributor or the project's main developer, CI systems act as a safety net, significantly reducing the likelihood of errors. Setting up CI for your project, ideally at an early stage, is a worthwhile investment in the long-term reliability and health of your codebase.

Unit Testing

Yousef — Sat, 11 Nov 2023 01:21:11 +0000

This week, my focus in the development of Learn2Blog centred on implementing unit testing, a crucial aspect of ensuring the reliability and stability of the project. In this blog post, I'll delve into the significance of unit testing and touch upon the broader concept of end-to-end testing.

The Importance of Testing

Unit testing and end-to-end testing are essential practices in software development, contributing to the overall quality and robustness of a project. Unit testing involves testing individual components or functions in isolation, ensuring they produce the expected output. On the other hand, end-to-end testing validates the entire system's functionality, simulating real-world scenarios.

xUnit.net

I opted to use xUnit.net, a testing framework recommended by Microsoft's dotnet documentation. xUnit.net is known for its simplicity and efficiency in writing and executing tests.

To integrate xUnit.net into your project, execute the following command:

dotnet add package xunit

For creating a testing project and class in Visual Studio (Code), consider adding the xunit.runner.visualstudio package, ensuring it's applied to the testing project, not the main one.

Creating a Testing Project

A testing project is crucial for maintaining a clean separation between the main project and its tests. In xUnit.net, each class and its methods in the testing project correspond to the classes and functionalities being tested.

Importing Main Project

To import the main project into the testing project, modify the TestingProject.csproj file:

<ItemGroup>
    <ProjectReference Include="Relative path to MainProject.csproj" />
</ItemGroup>

Ensure the path is correctly specified.

Writing Tests

I organized my tests by creating separate test classes corresponding to classes in the main project. For instance, the main project class CommandLineParser has a corresponding test class named CommandLineParserTests.

Utilizing ITestOutputHelper allows printing messages for each test and we can use it in our test class like so:

public class CommandLineParserTests
{
    private readonly ITestOutputHelper output;

    public CommandLineParserTests(ITestOutputHelper output)
    {
        this.output = output;
    }

   // rest of the code...
}

Here is an example of one of the tests the return outcome of running the app without any arguments:

[Fact]
public void TestNoArgumentReturnsNull()
{
    this.output.WriteLine("Should return null when user passes no arguments");

    var args = Array.Empty<string>();
    CommandLineOptions? options = CommandLineParser.ParseCommandLineArgs(args);

    Assert.Null(options);
}

In this code, the [Fact] attribute indicates it as a test method. It then creates an empty array to pass as args to simulate passing no arguments through the CLI and then asserts that options is returned as null.

Using `[Theory]` in xUnit

xUnit.net's [Theory] attribute simplifies testing scenarios with different sets of input data.

[Theory]
[InlineData("-o")]
[InlineData("--output")]
public void TestOutputArgument(string arg)
{
    this.output.WriteLine("Should return option with OutputPath == 'testOutput'");

    string outputPath = "testOutput";
    var args = new string[] { arg, outputPath, "input" };
    CommandLineOptions? options = CommandLineParser.ParseCommandLineArgs(args);

    Assert.Equal(outputPath, options?.OutputPath);
}

The [Theory] attribute allows running the same test with different input values. In this example, the test checks if the CommandLineParser correctly handles different forms of the output argument.

Incomplete Tests

While I successfully implemented several tests, some scenarios proved challenging. For example, testing the -c / --config argument requires mocking the config file, a task I documented in issue #18. Moq, a common tool for this in C# projects, was attempted but not fully successful.

Code Coverage

Code coverage is an essential metric indicating the percentage of code exercised by tests. Although I haven't yet implemented it in Learn2Blog, Microsoft guides generating code coverage reports for .NET projects here. The pursuit of 100% code coverage ensures a more comprehensive validation of code integrity.

End-to-End Testing

As of now, Learn2Blog lacks a dedicated end-to-end test. While core features have been extensively tested in unit tests, issue #20 has been created to address this gap.

End-to-end testing involves validating the entire application's workflow, ensuring all components work harmoniously. It complements unit testing by verifying the integration of various modules.

Lessons Learned

Reflecting on the testing process, it became evident that certain design flaws and bugs surfaced during testing. This emphasizes the importance of early test development, enabling the identification and rectification of issues before they escalate.

Automated tests, both unit and end-to-end, play a pivotal role in uncovering hidden bugs. The experience also highlighted the need for modular code, making it easier to test and maintain.

The bug with the StringWriter instance revealed during testing underscores the value of running multiple tests consecutively, mimicking real-world usage scenarios.

After squashing all of the different commits into a single one, it was merged into the main branch. You can review all the changes in 8e8edac.

Conclusion

In conclusion, the journey of implementing unit testing in Learn2Blog has been enlightening, exposing both strengths and areas for improvement. Embracing automated testing from the early stages is key to building a resilient and reliable software application. As development progresses, addressing the identified issues and continually expanding test coverage will be a priority for ensuring the long-term integrity of the project.

Enhancing Your Open-Source Project with Static Analysis Tools

Yousef — Fri, 03 Nov 2023 20:05:57 +0000

In the world of open-source development, improving the quality and accessibility of your project is of utmost importance. This week, I delved into the realm of static analysis tools to enhance my open-source project, Learn2Blog. In this blog post, I'll share my experiences and the steps I took to make my project more contributor-friendly, maintainable, and error-free.

Establishing a Solid Foundation

Contribution Guide: A Roadmap for Collaborators

One of the first steps I took was to add a contribution guide to my project. This document serves as a roadmap for potential collaborators, outlining the process of contributing to the project. It's essential to separate this guide from the README.md file to provide a clear, dedicated resource for contributors. This ensures that everyone is on the same page when it comes to making contributions.

Code of Conduct: Fostering a Welcoming Environment

To promote a positive and inclusive community around my project, I included a code of conduct. This document sets the expectations for behaviour within the project, emphasizing respect and collaboration. A clear code of conduct is vital to create a welcoming and productive environment for all contributors.

I used bttger's Contributing-Gen-Web tool to generate both the contribution guide and the code of conduct.

Formatting and Style Matters

Leveraging `.editorconfig` for Consistency

In my project, I incorporated a source code formatter provided by the dotnet framework. I also added .editorconfig file to the root directory of my project. This file defines formatting rules, such as indent style and indent size, ensuring consistency throughout the codebase.

The .editorconfig file's rules help maintain a clean and organized codebase, making it easier for contributors to work together cohesively.

Streamlined Tasks with Visual Studio Code

To simplify tasks for contributors, I updated the task.json file, a part of the Visual Studio Code generated files. This file contains custom-defined tasks that users can execute easily through the Command Palette. Additionally, contributors can run the format command via the command line interface (CLI). These instructions within the CONTRIBUTING.md file make it convenient for both experienced and novice contributors to participate effectively.

Keeping Code in Check

Introduction to StyleCopAnalyzer

For code quality and style enforcement, I integrated StyleCopAnalyzer from DotNetAnalyzers. This analyzer helps maintain code consistency and readability. It automatically checks the code every time you build the application.

I created a StyleCopAnalysers.ruleset file at the root of my project, which contains the ruleset for analysis. The tool not only identifies issues but also attempts to fix them, providing a log of any unresolved problems. In addition to running the analyzer upon build, the dotnet format command also runs any external analyzers that it detects by default as well.

Customizing StyleCopAnalyzer

While StyleCopAnalyzer offers valuable insights, it's important to adapt it to your project's specific needs. Style choices can be highly individual, and in my case, I modified the parameters to align with my personal preferences. For instance, I temporarily turned off the flag for the lack of documentation, with plans to address it later. The flexibility of this tool allows you to tailor it to your project's requirements easily.

Bringing It All Together

After making these improvements, I consolidated all my commits into a single one and merged the branch with the main branch. The use of static analysis tools not only enhanced my project but also streamlined the contribution process and improved the overall quality.

In conclusion, integrating static analysis tools can significantly benefit your open-source project. These tools help maintain consistency, enhance code quality, and foster a welcoming community of contributors. By following these steps, I've made Learn2Blog a more robust and accessible project. I encourage you to explore these tools and adapt them to your open-source endeavours, as the journey of open-source development is all about continuous improvement and collaboration.

Hacktoberfest 2023: Recap

Yousef — Fri, 27 Oct 2023 19:01:29 +0000

As October comes to a close, so does my journey through Hacktoberfest, a month-long celebration of open-source contributions. This year marked my first foray into this exciting world of collaborative coding, and I'm here to share the experiences and lessons learned during this remarkable journey. I'll be recapping my four-week progress through the lens of the blog posts I've written along the way.

Week 1: Finding the Right Project

In my first blog post, "Hacktoberfest: Good First Issue," I shared my initial steps into the world of open source. Finding the right project to contribute to can be a daunting task, but I outlined various strategies for identifying suitable projects and issues to work on. I also emphasized the importance of understanding the project's guidelines and the value of contributing to documentation tasks.

For my first contribution, I stumbled upon EnumConverter and fixed an issue in their documentation. Despite a minor misunderstanding in the initial pull request, the open-source community proved to be incredibly helpful and friendly. This first step boosted my confidence and set the stage for more significant contributions in the future.

Week 2: Beyond Code Contributions

In the second week, I continued my journey and explored the non-coding aspects of open source. In "Hacktoberfest: Week 2," I discussed the importance of understanding and adhering to project-specific guidelines, even for non-coding tasks. I shared my experience with enhancing podcast transcripts for Software Engineering Unlocked, a podcast by Michaela Greiler. This contribution involved improving the clarity and readability of podcast transcripts.

The collaborative nature of open source became evident as I collaborated with the podcast's author to clarify various aspects of the transcripts. This taught me that open-source contributions come in various forms, and all forms of contributions are valuable.

Week 3: Adding Value to Explore-cli

Week 3 of Hacktoberfest presented a unique opportunity to contribute to explore-cli, a command-line tool for SwaggerHub Explore, an essential tool for API professionals. I focused on enhancing the ExportedAt attribute within the codebase. The journey taught me about the collaborative spirit of open source, even when maintainers are actively involved in the project. External contributors can bring fresh perspectives and innovative solutions. I documented my contributions in depth in my previous post, "Hacking Away in Week 3 of Hacktoberfest."

My contributions to explore-cli emphasized the importance of code quality and consistency. This experience reminded me that every contribution, whether small or significant, adds value to the open-source landscape.

Week 4: Wrapping up with CrispyWaffle

As the final week of Hacktoberfest approached, I delved into CrispyWaffle, a toolkit for .NET projects. My contributions included code refactoring, removing unnecessary retry loops, and simplifying code logic. The experience was both rewarding and educational, emphasizing the significance of improving code quality. My post "Last Week of Hacktoberfest" outlines my journey.

My contributions to CrispyWaffle were quickly accepted by the project's maintainers, underscoring the collaborative nature of open source. This journey has been a testament to the power of community and the impact that small changes can make.

The Bigger Picture

Hacktoberfest 2023 has been a remarkable journey. It began with finding the right project, expanded into non-code contributions, and then led me to explore various codebase improvements. Through it all, I learned that open-source contributions come in many forms, each valuable in its own right.

Open source is not just about code; it's about community, collaboration, and the collective effort to improve technology. As this year's Hacktoberfest comes to a close, I'm eager to continue my journey in the open-source community, armed with the knowledge and experience gained during this exciting month. I look forward to more contributions, more collaboration, and more positive impact in the world of open source.

Last Week of Hacktoberfest

Yousef — Fri, 27 Oct 2023 18:42:02 +0000

As the last week of Hacktoberfest comes to a close, I'm thrilled to share my recent contributions to the open-source community, particularly to the CrispyWaffle project, a toolkit for .NET projects. In this blog, I'll recount my journey and the changes I made to improve the project.

Getting Started

I kicked off my Hacktoberfest contributions by diving into CrispyWaffle, a project that caught my attention due to its importance in the .NET ecosystem. The maintainers had an open issue #211, which required assistance in removing a retry check within one of their classes. After discussing the changes and receiving their initial approval, they encouraged me to seek additional areas for improvement within the codebase. Eager to make a positive impact, I accepted the challenge.

The Code Refactoring

1. Removing the Retry Rule in `FtpClient.cs`

The first issue to tackle was in the FtpClient.cs file, This class used a while loop to manage retry attempts. Here's a comparison between the old and new code:

Old Code:

private bool CreateInternal(string path, byte[] bytes)
{
    var result = false;
    var attempts = 0;
    while (true)
    {
        attempts++;
        try
        {
            // ... (rest of the code)
        }
        catch (WebException e)
        {
            if (attempts >= 3)
            {
                throw new FtpClientException(path.GetPathOrFileName(), "create", e);
            }
            Thread.Sleep(1000);
        }
    }
    return result;
}

New Code:

private bool CreateInternal(string path, byte[] bytes)
{
    var result = false;
    try
    {
        // ... (rest of the code)
    }
    catch (WebException e)
    {
        throw new FtpClientException(path.GetPathOrFileName(), "create", e);
    }
    return result;
}

Explanation: The old code used a while(true) loop for retry attempts, which is generally not a good practice. It also included a counter (attempts) to track the number of retries and a subsequent if statement to check if the maximum retry limit was reached. In the new code, I removed the loop and the unnecessary variables, simplifying the code and making it more readable.

2. Flipping `NOT` Conditions

In the original code, I noticed instances where conditions were negated, making them less intuitive. I proposed changing these NOT conditions to a more straightforward format:

Old Code:

request.Method = !string.IsNullOrWhiteSpace(uri.GetFileExtension())
                    ? WebRequestMethods.Ftp.GetFileSize
                    : WebRequestMethods.Ftp.ListDirectory;

New Code:

request.Method = string.IsNullOrWhiteSpace(uri.GetFileExtension())
                    ? WebRequestMethods.Ftp.ListDirectory
                    : WebRequestMethods.Ftp.GetFileSize;

Explanation: Writing code without negations is a better practice because it enhances code readability. The new code provides a more intuitive understanding of the logic, making it easier for other developers to follow.

3. Better Resource Handling in `ExistsInternal`

In the ExistsInternal method, I found several areas where resource handling could be improved:

Old Code:

private bool ExistsInternal(string path)
{
     var result = false;
     Stream responseStream = null;

     try
     {
          LogConsumer.Info(
               "Checking in FtpClient the path/file: {0}",
               path.GetPathOrFileName()
          );
          var uri = new Uri(path);
          var request = (FtpWebRequest)WebRequest.Create(uri);
          request.Credentials = new NetworkCredential(_userName, _password);
          request.Method = !string.IsNullOrWhiteSpace(uri.GetFileExtension())
              ? WebRequestMethods.Ftp.GetFileSize
              : WebRequestMethods.Ftp.ListDirectory;
          request.Timeout = 30000;
          request.ReadWriteTimeout = 90000;
          request.UsePassive = true;
          var response = (FtpWebResponse)request.GetResponse();
          var status = response.StatusCode;
          responseStream = response.GetResponseStream();
          if (responseStream == null)
          {
               throw new InvalidOperationException("Response stream is null");
          }

          using var reader = new StreamReader(responseStream);
          responseStream = null;
          while (!reader.EndOfStream)
          {
              _files.Enqueue(reader.ReadLine());
          }

          if (!string.IsNullOrWhiteSpace(uri.GetFileExtension())
                   && status == FtpStatusCode.FileStatus
                   || status == FtpStatusCode.OpeningData)
          {
              result = true;
          }
     }
          catch (WebException)
          {
              result = false;
          }
          finally
          {
              responseStream?.Dispose();
          }

          return result;
}

New Code:

private bool ExistsInternal(string path)
{
     try
     {
          LogConsumer.Info("Checking in FtpClient the path/file: {0}", path.GetPathOrFileName());
          var uri = new Uri(path);
          var request = (FtpWebRequest)WebRequest.Create(uri);
          request.Credentials = new NetworkCredential(_userName, _password);
          request.Method = string.IsNullOrWhiteSpace(uri.GetFileExtension())
          ? WebRequestMethods.Ftp.ListDirectory
          : WebRequestMethods.Ftp.GetFileSize;
          request.Timeout = 30000;
          request.ReadWriteTimeout = 90000;
          request.UsePassive = true;

          using var response = (FtpWebResponse)request.GetResponse();
          using (var responseStream = response.GetResponseStream())
               {
                    using var reader = new StreamReader(responseStream);
                    while (!reader.EndOfStream)
                    {
                         _files.Enqueue(reader.ReadLine());
                    }
               }

               return string.IsNullOrWhiteSpace(uri.GetFileExtension())
                    ? response.StatusCode == FtpStatusCode.OpeningData
                    : response.StatusCode == FtpStatusCode.FileStatus || response.StatusCode == FtpStatusCode.OpeningData;
               }
                    catch (WebException)
               {
                    return false;
               }
}

Explanation: In the new code, I improved resource handling by using using statements to ensure that resources are properly disposed of when they are no longer needed. Additionally, I removed the result variable, simplifying the code and improving its clarity.

Wrapping Up

My Hacktoberfest journey has been both rewarding and educational. I've had the opportunity to contribute to the open-source community and make meaningful improvements to a valuable project. These changes not only enhance the project's functionality but also make it more accessible for other developers.

As a final note, I'm thrilled to share that my contributions have already been merged into the CrispyWaffle project. You can check out my Pull Request and the final merge commit. The CrispyWaffle team immediately approved and merged my proposed changes without any further change requests, underlining the collaborative spirit of the open-source community. As Hacktoberfest comes to an end, I look forward to more open-source contributions in the future.

Hacking Away in Week 3 of Hacktoberfest

Yousef — Fri, 20 Oct 2023 12:28:22 +0000

Week 3 of this annual event brought a unique opportunity to contribute to explore-cli, a nifty utility CLI designed to facilitate data import and export in SwaggerHub Explore, an integral tool for API professionals. If you're not yet familiar with SwaggerHub Explore, it's a powerful component of the SwaggerHub platform, that streamlines data management for API designers and developers.

The Issue: Elevating the `ExportedAt` Attribute

My contribution for this week was centred around a specific issue in the explore-cli repository. The issue, identified as Issue #8, revolved around enhancing the ExportedAt attribute found in the Program.cs file. Initially, this attribute contained only a timestamp representing time, neglecting to include the date.

Here's a glimpse of the original code:

// construct the export object
var export = new ExportSpaces()
{
    Info = new Info() { ExportedAt = DateTime.UtcNow.ToLongTimeString() },
    ExploreSpaces = spacesToExport
};

In my quest to enhance this utility, I proposed a modification that incorporated both the date and time into the ExportedAt attribute:

var export = new ExportSpaces()
{
    Info = new Info() { ExportedAt = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ss.fffZ") },
    ExploreSpaces = spacesToExport
};

This adjustment introduced a standardized timestamp format, including both date and time, making it more informative and user-friendly.

The Pull Request Journey

Following the code modification, I promptly created a pull request to merge these changes into the explore-cli repository. An interesting twist occurred during this process. The maintainers decided to create their own pull request to my topic branch on the repository forked to my GitHub.

This action essentially meant that they crafted the code to align with their precise requirements. Once I approved their pull request, their contributions seamlessly integrated into my initial pull request, a curious instance of a project's maintainers collaborating on their own project through an external contributor's repository. This raised an intriguing question: Why enlist external contributions when the project's maintainers are actively involved in the development process?

This question often arises in open-source projects, and the answer lies in the diversity of perspectives and ideas that external contributors bring to the table. Even when maintainers are deeply involved, fresh insights from the community can lead to innovative solutions and foster a sense of community and collaboration. It's a testament to the inclusive nature of open-source, where different viewpoints can lead to enhanced project quality and efficiency. This collaborative spirit is what makes open-source development a dynamic and ever-evolving ecosystem.

Nevertheless, this experience turned out to be highly educational for me. I took the opportunity to refine their code, aligning it with industry standards in terms of spacing, indentation, and overall formatting. It underscored the significance of code quality and consistency within the realm of open-source contributions.

A Valuable Learning Experience

My involvement in Hacktoberfest Week 3 wasn't just about code changes; it was also a valuable learning experience. While my solution effectively achieved the desired outcome, the approach suggested by the project's author in their pull request proved to be more efficient and concise.

In conclusion, my journey in Hacktoberfest Week 3 was an enriching experience. It highlighted the collaborative nature of open-source development and emphasized the significance of maintaining code quality. Despite the occasional twist, it showcased the value of collective efforts, both in terms of code enhancement and learning opportunities. Open source truly offers a fascinating journey where each contribution, no matter how small or significant, adds value to the larger landscape of technology and innovation.

Git Rebase: Learn2Blog Refactor

Yousef — Sat, 14 Oct 2023 22:34:59 +0000

This week, I embarked on a journey to enhance my ongoing open-source project, Learn2Blog. This is a command-line tool I developed to convert plain text and markdown files into HTML, making it a handy utility for bloggers and content creators. In this article, we'll explore the recent refactoring efforts undertaken to improve the codebase's maintainability, extensibility, and overall code quality.

The Need for Refactoring

Refactoring is a crucial practice in software development that involves restructuring and optimizing code without changing its external behaviour. The primary motivations behind the refactoring of Learn2Blog were as follows:

Modularity for Future Development: The original code was functional but lacked the modularity required for future feature additions and maintenance. By refactoring, we aimed to make the codebase more extensible and easier to work with.
Code Quality: Improving code quality not only makes the project more maintainable but also enhances its overall performance. This is crucial for an open-source project meant for public use.
Better Readability: Code readability is essential for collaboration. By making the code more readable and organized, it becomes more accessible to potential contributors.
Bug Fixing: Addressing longstanding bugs and issues to ensure a smoother user experience was another vital goal.

Refactoring: Step by Step

Let's dive into the step-by-step process of refactoring Learn2Blog. We'll discuss the improvements made to the project's structure, as well as changes to the FileProcessor class.

Improved Project Structure

In the refactored code, we introduced a cleaner project structure to enhance organization and code separation. We created a Learn2Blog.cs file, which serves as the entry point for the application. This centralization simplifies the entry point and makes it more cohesive.

public class Learn2Blog
{
    public static void Run(string[] args)
    {
        CommandLineOptions options = CommandLineParser.ParseCommandLineArgs(args) ?? new CommandLineOptions { InputPath = "", OutputPath = "" };
        if (options.ShowVersion) CommandLineUtils.ShowVersion();
        else if (options.ShowHelp) CommandLineUtils.ShowHelp();
        else FileProcessor.ProcessFiles(options);
    }
}

This new structure facilitates ease of understanding and navigation, which is crucial when working on a collaborative, open-source project. Now, the Main function in Program.cs contains the following code:

class Program
    {
        static void Main(string[] args)
        {
            Learn2Blog.Run(args);
        }
    }

FileProcessor - Breaking Down the Complexity

The most significant improvement during this refactoring process happened in the FileProcessor class. This class is responsible for processing input files. In the original code, file processing logic was coupled with command-line argument parsing, creating a challenging codebase to manage.

In the old code, the FileProcessor class did not exist, and the file processing logic was scattered throughout the application. In the refactored code, the FileProcessor class now separates file-processing logic and command-line argument parsing. This separation enhances the code's modularity and makes it easier to maintain and extend.

Handling Single File Processing

One of the key changes in the refactored code is the introduction of the ProcessFile method. This method is responsible for processing a single file. Here's how it works:

private static void ProcessFile(string inputPath, string outputPath)
{
    string ext = Path.GetExtension(inputPath);
    string html;
    try
    {
        string text = File.ReadAllText(inputPath);
        string body = "";

        if (ext == ".txt")
        {
            body = ProcessText(text);
        }
        else
        {
            body = ProcessMarkdown(text);
        }

        html = HtmlGenerator.GenerateHtmlFromText(Path.GetFileNameWithoutExtension(inputPath), body);
    }
    catch (Exception ex)
    {
        CommandLineUtils.Logger($"Error processing file {inputPath}: {ex.Message}");
        return;
    }

    string outputFileName = GetUniqueOutputFileName(inputPath, outputPath);
    SaveHtmlFile(outputFileName, html);

    CommandLineUtils.Logger($"File converted: {outputFileName}");
}

The ProcessFile method efficiently handles the conversion of individual input files. It identifies the file type, processes the content, generates HTML, and saves it with a unique filename to avoid overwriting existing files.

Processing Files in a Directory

In the refactored code, we introduced the ProcessFilesInDirectory method. This function is responsible for processing all files in a specified directory. Here's how it works:

private static void ProcessFilesInDirectory(string inputDirectory, string outputDirectory)
{
    string[] files = Directory.GetFiles(inputDirectory, "*.txt").Union(Directory.GetFiles(inputDirectory, "*.md")).ToArray();

    if files.Length == 0)
    {
        CommandLineUtils.Logger($"No .txt or .md files found in directory {inputDirectory}");
        return;
    }

    CommandLineUtils.CreateOutputDirectory(outputDirectory);

    foreach (string file in files)
    {
        ProcessFile(file, outputDirectory);
    }
}

The ProcessFilesInDirectory method scans the specified directory for .txt and .md files, and then, for each file found, it calls the ProcessFile method for individual file processing. This separation of responsibilities enhances code modularity and maintainability.

Ensuring Unique Output Filenames

Another noteworthy addition in the refactored code is the GetUniqueOutputFileName method. This method is responsible for generating a unique output filename when saving converted HTML files. This approach ensures that no files are inadvertently overwritten.

private static string GetUniqueOutputFileName(string inputPath, string outputPath)
{
    string fileName = Path.GetFileNameWithoutExtension(inputPath);
    string outputFileName = Path.Combine(outputPath, fileName + ".html");

    int fileNumber = 1;
    while (File.Exists(outputFileName))
    {
        outputFileName = Path.Combine(outputPath, $"{fileName}_{fileNumber}.html");
        fileNumber++;
    }

    return outputFileName;
}

Improved HTML Generation

In the refactored code, the HTML generation logic has been moved to a separate class called HtmlGenerator. This separation enhances code modularity. Instead of calling AppendLine repetitively, the HtmlGenerator class generates the HTML content as a single string, which embeds both the title and body.

Here's how the HtmlGenerator class works:

public static class HtmlGenerator
{
    public static string GenerateHtmlFromText(string title, string body)
    {
        string html = $@"
<!DOCTYPE html>
<html>
<head>
    <title>{title}</title>
</head>
<body>
    {body}
</body>
</html>";

        return html;
    }
}

This approach simplifies HTML generation, making the code more readable and maintainable.

Git Rebase for a Cleaner History

Maintaining a clean and organized Git history is essential for open-source projects. During this refactoring process, I used Git's interactive rebase feature to squash and clean up my commit history. This approach ensures that the project's history is coherent and easier to review for potential contributors.

$ git rebase main -i
$ git push origin main

I also recommend using the GitLens extension for Visual Studio Code, which provides a convenient GUI for Git rebase operations.

Rigorous Testing

Throughout the refactoring process, I performed rigorous testing to ensure that all existing functionalities were preserved as intended. This included manual testing only, as I have not developed a unit tester for this application yet. But that will be coming in the next few weeks, so stay tuned! By running tests at each refactoring step, I could quickly identify and rectify any issues and bugs before moving on to the next phase.

A Few Bumps in the Road

As with any significant code refactoring, some issues surfaced along the way. But in this case, nothing major. There was a minor hiccup with my .gitconfig file, which was not correctly linked to my external editor. After resolving this issue and correctly linking Visual Studio Code as my external editor, the rebase process proceeded smoothly.

The Final Commit

After completing the refactor, I squashed all 14 commits into a single one to create a clean and cohesive history. Using git commit --amend, I updated the commit message for this final commit, and then I merged it into the main branch and pushed the changes to GitHub. The final commit can be reviewed here.

I also pushed all the changes made during the refactor to a dedicated branch called refactor. This branch contains the entire commit history related to this refactoring effort.

Conclusion

Code refactoring is a vital part of maintaining a healthy open-source project. It improves code quality, enhances modularity, and makes the project more inviting to contributors. By following best practices and rigorous testing, we can ensure that existing functionalities remain intact while improving the codebase.

In the case of Learn2Blog, this refactoring effort has laid the groundwork for future enhancements and a more user-friendly experience. If you're interested in contributing to this project or exploring the changes in detail, please check out the Learn2Blog repository on GitHub. Your contributions are always welcome!

DEV Community: Yousef

Reflecting on the Journey with Explore.CLI

Achieving Goals and Implementing Technical Features

Managing Expectations and Time

Learning from the Process and Community Interaction

Concluding Thoughts

Explore.CLI - Progress

Enhancing the 'Import' Feature

Code Refinement and Bug Fixing

Code Snippets

Documentation and Pull Request

Conclusion

Planning More Enhancements for Explore.CLI

Introduction to Future Contributions

Planned Enhancements and Strategy

Expanding the 'Import' Feature

Removing Deprecated Feature

Addressing Past Bugs

Approach and Reflections

Learning and Adapting

Preparatory Work

Documentation Updates

Conclusion and Upcoming Update

The NuGet Publishing Puzzle

Navigating the Challenges with Learn2Blog

Preparing for NuGet Publication

Adhering to the NuGet Documentation

Facing the Unexpected

Exploring Potential Issues

A Stalemate and Further Exploration

A Temporary Pause

Reflecting on the Process

Enhancing Explore.CLI

Introduction to Explore.CLI

Initial Steps and First Contributions

Issue #6: Enhancing Export Functionality

Building Upon the Foundation: Issue #4

Refining and Resolving Challenges

Workflow and Platform-Specific Considerations

Release of Explore.Cli v0.4.0

Reflecting on the Experience

GitHub Actions Workflow

Introduction

Setting Up the Workflow

Hiccups Along the Way

Contributing to Node-TILify

Conclusion

Unit Testing

The Importance of Testing

xUnit.net

Creating a Testing Project

Importing Main Project

Writing Tests

Using [Theory] in xUnit

Incomplete Tests

Code Coverage

End-to-End Testing

Lessons Learned

Conclusion

Enhancing Your Open-Source Project with Static Analysis Tools

Establishing a Solid Foundation

Contribution Guide: A Roadmap for Collaborators

Code of Conduct: Fostering a Welcoming Environment

Formatting and Style Matters

Leveraging .editorconfig for Consistency

Streamlined Tasks with Visual Studio Code

Keeping Code in Check

Introduction to StyleCopAnalyzer

Customizing StyleCopAnalyzer

Bringing It All Together

Hacktoberfest 2023: Recap

Week 1: Finding the Right Project

Week 2: Beyond Code Contributions

Week 3: Adding Value to Explore-cli

Week 4: Wrapping up with CrispyWaffle

The Bigger Picture

Last Week of Hacktoberfest

Getting Started

The Code Refactoring

1. Removing the Retry Rule in FtpClient.cs

Using `[Theory]` in xUnit

Leveraging `.editorconfig` for Consistency

1. Removing the Retry Rule in `FtpClient.cs`

2. Flipping `NOT` Conditions

3. Better Resource Handling in `ExistsInternal`

The Issue: Elevating the `ExportedAt` Attribute