Contribute an Epic Stack Example

Kent C. Dodds: 0:01 You want to get something into the Epic Stack. The best way to do this is by creating an example first. Demonstrate why the change that you want to have happen makes a lot of sense and demonstrate how to make that change happen.

0:14 The benefit of doing this is that even if it doesn't end up making it into the Epic Stack, at least you'll be able to demonstrate to other people how they can integrate your service or how they can use your library or whatever it is.

0:27 We're going to do this by adding CSRF protection to our forms in the Epic Stack. Then maybe, eventually, that will land as a built-in part of the stack. I want to show you how to create an example that is really effective at demonstrating to myself and to others why the changes that you want to make are a good idea and how to make those changes.

0:55 We'll follow the instructions here. We're going to create a new Epic Stack application. By doing this, we'll go into our terminal right here. We'll say create this Epic Stack app. Let's open this up here. Let's call this epic-stack-with-csrf, or you could say, "csrf-example," whatever.

1:26 There's this "with" prefix that is not important. I don't really care what you call this repo. This is going to be on your own GitHub repository when it's added to this. Have it be whatever you want it to be. It's fine.

1:41 We'll speed this up here really quick. Because this is just an example and we don't really care to have it deployed -- it doesn't actually need to be deployed to be a useful example -- we're not going to deploy it. I'm just going to say no here.

1:56 Now, the first thing that we're going to do is we'll say, "cd" into our epic-stack-with-csrf. We'll look at our git status. It's not a git repo. We're going to git init. Now we'll git add everything and commit with init.

2:14 This part is actually really important because it allows people to see just the changes that you made to the Epic Stack to add your features. We want to make an initial commit right after we've set up the repo.

2:29 Then we're also going to open up our editor right here. Because we don't actually want to deploy, we're going to turn off the deploys right here. Let's just comment this out. We'll add another commit, git commit disable deploys. You could also do that as part of your init commit if you want to. That's not all that important there.

2:55 Just the point is that you want to make sure that there are very specific commits that are relevant to the changes that you're making. You could even make multiple commits for each step if you want to, but for this particular example, we'll just make a single commit.

3:09 As interesting as this is, I'm actually going to skip this for us so that you can skip to the end. At this point, you're just going to make whatever changes you need to make for your example to be working. Then you'll join back up with me when it's time to do your docs.

3:23 Once you've finished, you want to make sure of two things. One, that you've only changed as much as necessary for your specific example. Don't add a bunch of tangentially related things because it could distract from the main purpose of the example. Try to focus on what the example is actually demonstrating.

3:40 The second one is make sure that you're actually testing the changes that you're making. If that involves writing automated tests, then that's awesome. If that involves running the automated tests that we have, also awesome. There should be GitHub workflows for running the automated tests as well. That's helpful too.

4:00 Then, of course, you want to manually test things to make sure that things are working. Once you've verified that everything has changed the way that you want to, you can take a look at the git diff and make sure that you haven't changed more things than you actually expect.

4:12 Then you can write some documentation, just a little bit of an explanation of what the example is all about. If you take a look at the existing examples that we have, you can see that the documentation does not have to be really well spelled out or anything necessarily.

4:30 It just needs to be relatively basic on the steps needed to accomplish the task because a lot of the benefit actually comes from people looking at the commit history and saying, "Oh, OK. So here is the commit, and here are the things that they changed to bring Framer into the Epic Stack," for example.

4:49 For us, we're just going to delete all of this stuff. We'll give this the title of "Epic Stack with CSRF Protection." Then we write out some documentation, which I will do now. Awesome. Now we've got the docs. This is just enough for people to be able to follow along, look at the commit history, and see the changes that were necessary.

5:11 In some cases, that might be quite a bit, especially if it involves infra stuff so you need to set secrets and stuff. In other cases, it's just a couple simple steps. Whatever it is, you have the documentation that makes it easy for people to integrate and also easy for me to take a look at and determine whether I want to bake that into the Epic Stack as a built-in part of the stack.

5:32 Now we simply need to create a repo. You can go to repo.new and create the repository here. We're going to call it epic-stack-with-csrf. This will be under myself. An example of the Epic Stack with CSRF protection on forms. Then we create that repository. We follow the instructions for pushing an existing repository.

6:04 Let's make sure we look at the status, git add everything. We'll commit this as "Add CSRF protection with remix-utils." Then we can copy this and paste that. Now we've got the Epic Stack with CSRF on here.

6:23 Another thing that you should do is add a topic for the epic-stack and epic-stack-examples, or example, singular. Because what this will do is it will add your example to the topic on GitHub so that people can look at this topic and see all of the examples really easily, in addition to those that are listed in the examples docs on the Epic Stack.

6:49 The last step is to come into the examples and just hit the little pencil icon. This will fork the repository for you and simply add another line to the bottom of this. Now we'll commit the changes. For you, you're going to be committing to your own repo. I'm going to create a branch to kind of simulate that sort of thing. You can feel free to elaborate here if you like.

7:15 For examples, I can just kind of look at things and know. No test plan is necessary. The checklist doesn't matter. Screenshots would be useful for different things. In our case, the CSRF thing, there's nothing really to screenshot. Definitely useful if what you're doing involves some sort of UI or some terminal output. Something like that could be very useful here as well.

7:39 I'm going to just clear all that out. We'll just create the pull request. Then you'll get it merged. Then I'll come in here. I'll merge it. I'll be like, "Thanks. You're awesome."

7:47 Thank you for taking the time to create an example. It helps a ton, just an enormous amount, for me when evaluating different things that I want to have built in and for other people who want to be able to use those things today without waiting for it to get built in. I hope that helps. Thank you so much. We'll see you later.