Back Button Tooling

How to Manage an Open Source Project

Managing a popular open source project can be daunting at first. How do we maintain all these issues, or automatically trigger our test suite for incoming PRs? And what's a useful workflow for brainstorming and adding new features?

In this series, together, we'll manage and maintain an open source forum, called Council, that we originally built from scratch here at Laracasts.

Advanced
Difficulty
24 episodes
4:42:41 hrs
Start Series
    1. Run Time 5:18 Free

      To begin this series, let's push our project to GitHub, so that anyone can install it - and even contribute to make it better.

    2. Our project will be of little use, if the general public doesn't know how to install it. Let's work through that entire process, while making installation notes for the project's readme file.

    3. In the previous issue, we created our first GitHub issue: "Unconfirmed users should not be given the opportunity to prepare create forum threads." Let's resolve that very issue in this episode.

    4. We already have a number of issues and pull requests up on GitHub. Let's get to work on these, as we learn the basic day-to-day workflow for maintaining any open source project.

    5. Naturally, a core component to managing any open source project is integrating new features and functionality. With that in mind, let's extend our forum with "user reputation." This way, for each participant in the forum, a number that indicates their participation and experience level may be assigned to them.

    6. We now have a basic reputation system in place, but I think it could use some refactoring. At the moment, if somebody joined your team, how would they know where, and on what conditions, reputation is awarded to a user? It's not easy at that moment. Instead, let's elevate this concept of "reputation" to a first class citizen.

    7. Now that our tests are returning green, let's display each user's reputation on the page, next to their respective usernames.

    8. At the moment, any user can "game the system" by rapidly creating and deleting threads or replies. We must ensure that, if a user's thread or reply is deleted, we reduce their reputation to match.

    9. Yeah, yeah, this one will be a little on the mundane side. Nonetheless, it needs to be addressed. Most successful open source projects will include, within the root of the project, the following three documents; LICENSE, CODE_OF_CONDUCT, and CONTRIBUTING. Let's do a quick overview in this episode.

    10. Not all PRs amount to simple formatting and bug fixes. Often, you'll receive significant feature additions that affect dozens of files. In these cases, it's important to fully review, test, and even tweak the code before merging it into your codebase. Let's work through that process together.

    11. Run Time 8:16 Free

      Let's set up a continuous integration server with Travis CI. This way, we can automate the process of building and testing our project each time a new commit is made, or a PR is presented.

    12. Run Time 8:32 Free

      StyleCI is an excellent service for automating the process of analyzing and performing style-guide fixes. As an example, if your project conforms to PSR-2, but a pull request is submitted that doesn't adhere to that standard, wouldn't it be great if we could automatically fix those issues without nagging the contributor to do it manually?

    13. It looks like a PR that adds syntax highlighting just came in. Let's work through the code changes, merge it in, and then apply a bit of refactoring to clean things up.

    14. If you're not careful, you might find yourself merging PRs without fully understanding what the underlying code does. "Hey, the tests return green, so it's safe to merge. Right?" Try to avoid this mindset. It's vital that you study the code behind every pull request. Otherwise, you might end up with a codebase that in no way reflects your original vision and ideas for how the project should be structured.

    15. Let's resolve this issue on GitHub. As part of the process, we'll need to do a quick review of dispatching jobs, and running queue workers.

    16. In this episode, we'll work through a new PR that adds support for pinning one or more threads to the top of all results. This can be useful for important news-related posts, codes of conduct, etc. Let's review the PR, make any necessary tweaks, and merge it into master!

    17. Today, we need to build upon a recent commit that added support for editing channels. The PR stopped just short of allowing administrators to archive channels. As it turns out, this can be a bit tricky. So let's figure out our course of action, and implement it with TDD.

    18. It seems like, just about in all cases, when we fetch a collection of channels, they should exclude any archived records. What if we instead made that a global scope?

      View the commit for this episode on GitHub.

    19. When submitting a pull request to fix a bug, it's vital that a test accompanies your fix. The maintainer can't just take your word for it. Show them what the problem is. "Hey, if we take this specific route through the code, everything blows up. Here's a test that proves it."

    20. After a week of writing CSS, I'm ready to merge in the first draft of the new "Council" UI. We're not yet finished, however; there's still work to be done. The profile page hasn't yet been styled, and the forum requires the necessary responsive Tailwind classes to display correctly on mobile devices. We'll tackle these lingering tasks soon, together.

    21. It looks like we have a pull request to upgrade Council to Laravel 5.6. Let's work through that PR in this episode, at which point half-way through, we'll encounter an odd, mysterious application bug related to foreign Sqlite constraints in 5.6.

    22. Per my request in a recent episode, we now have a new PR for displaying a user's profile activity. However, it's still marked as a "Work in Progress." This means, while most of the functionality has been implemented, we'll need to pay extra attention to any remaining loose ends that should be filled in. Let's begin working through it in this episode together.

    23. When we call the path method on a Reply instance, it doesn't take into account the fact that all replies are paginated. This means all reply paths will send you to page one, rather than the page that you'll find the actual reply. We can't have this. Let's figure out how to calculate the full URL, based on the specified pagination settings.

      Homework: There's one problem with our completed example. Do you see what it is? Leave a comment below if you find it. In the following episode, we'll address the issue together.

    24. GitHub releases offer us a way to package up software for our users. Maybe a person wants the latest 2.0 release of your code. Or maybe, due to the limits of their system, they need to stick with the 1.0 version. No problem. All of this is a cinch. In this lesson, we'll review how to use Git tags to create new releases.

You May Also Enjoy...

Here are some additional series that may be up your alley.

Laravel Let's Build A Forum with Laravel and TDD
Advanced
Difficulty

A forum is a deceptively complex thing. Sure, it's made up of threads and replies, but what else might exist as part of a forum? What about profiles,...

19:29:26 hrs
Play