508.dev has many self-funded projects, all of which are libre / open-source, none of which we're profiting from (yet). We have these projects for several reasons.
- So as to have a co-op portfolio with shareable code to show off our skills
- So as to provide opportunities for our engineers to get projects on their personal portfolios that are of a higher quality than the typical personal project
- Per our values, we are constantly striving to improve our abilities, and the best way to do that is work on projects using new tech
- We need a way to evaluate engineering ability of our members and the most effective way to do that is working on a project together
- Keep our skills warm between projects
If you're interested in working on one of these projects for no other reason than to get a better-than-normal "personal project" on your portfolio, we welcome contributions from people of all skills levels! I'll outline how to do so below.
Find a Project and Task
Your first step is to pick a project and/or task that interests you and matches your skill level. Never fear, we really do have tasks available for ALL skill levels!
There's a couple ways to find a project that interests you. First, you could just browse all our repositories and find one that strikes your fancy. Once you find one, for example the repo for this website, you should check out the Projects tab of the repo. For this website, that would be here. Inside that tab you should find a project with the word "Kanban" in it. A Kanban is a project management tool where tasks are displayed as cards with a single succinct sentence describing the task, lain out in columns describing the state of that task (usually some manner of TODO, DOING, IN REVIEW, and DONE. The kanban for this website is available here. Here's how a Kanban for a project might look:
| Ready | In Progress | In Review | Done |
|---|---|---|---|
| Pop-out list of "technologies" under client section should take up more horizontal space when available | Fix broken link in index.html#Engineer Index | ||
| Navigation items should have some kind of styling for a given link when on that link's page |
On Github, you can click individual cards to see a description and more info. You can click through cards until you find one you like, and then when you're ready to work, assign it to yourself, and move it to the In Progress column.
If you don't want to go project to project to find an issue, we also have a comprehensive ticket table that lists out all issues (tickets, TODOs) we have across all 508 projects. We try to keep this table updated with estimated skill level as well.
Clone a Project
After choosing a project, you need to get the project code on your machine. To make that happen, you'll need you'll need git, a version control software. With that installed, you'll use git from the terminal to "clone," or download, the code onto your machine. Then, you'll to configure SSH keys on your machine.
Then, you'll need to fork the repo, or, make your own version of it under your personal Github account.
With that done, on your fork of the project's Github page, there's a big green button labeled Code, with a dropdown built in. Click the button, ensure SSH is the tab selected. Grab the URL there, then in your terminal, cd to a nice place to keep code, and do git clone {{URL}}. If you've set up everything correctly, git should download the repo to your machine, with all the git history and branches as well.
Make a Branch
Once you've chosen an issue and cloned the repo, and claimed a ticket so nobody else works on it, you need to find a way to keep your new work separate from any other work people are doing. In git, the way to do that is branching. To create a branch, do git checkout -b {{branchname}}. A good branch name should be some personal identifier, such as your name, and a shortened version of the ticket title. For example, caleb/add-blogpost-contributing-508. With the branch created, you're ready to start coding!
Using git for committing and etc is out of scope for this article. Atlasssian has a decent article on the subject.
Issue a Pull Request (PR)
When your code is ready, you tell the rest of us by issuing a Pull Request (PR). You worked on your own repo and your own branch, so you'll be issuing a PR to the 508 repo from across forks and branches.
To do so, visit the Github page for the 508 version of a given project repo. The url should be something like github.com/508-dev/{{project}}. If you're lucky, Github will have a little banner displayed with a shortcut to create a PR from your branch with recent pushes directly. If not, you'll need to do it yourself, by clicking the Pull Requests tab. From there, click the green Create Pull Request button. You'll be shown a series of dropdown menus for repos and branches. Annoyingly, you must do the dropdowns left to right, as changing one of the dropdowns on the left will reset the state of those on the right.
In the far-left dropdown, Base Repository, make sure this is set to the 508 version of the repo, not your own. If you don't see this option, look for compare across forks, visible as a link somewhere on the page. The base dropdown should be main. The Head Repository will be your repository, and the compare will be your branch in your repository.
With all dropdowns selected correctly, the area below the dropdowns should be populated with all the differences between your branch and the main branch of the 508 version of the repo. If everything looks good, click Create Pull Request. You'll be shown a title and comment box, which you should fill out in a fair amount of detail. Then, click Create Pull Request again. You're done!
Just kidding. At this point, a 508 core member will review your code. Almost always, there will be a change request. Keep an eye on your pull request, as people will probably be commenting and making change requests. Try not to take this personally: it's extremely rare for an engineer to get something perfect on the first try, especially when you're new to a project, no matter the skill level. If there are change requests, you can update the PR by simply pushing to it from your machine.
After a couple iterations of that, then you're done! Your code will be merged into the project and 508 core members will handle deployment. Congratulations, you can now put the whole project on your portfolio! Yup, your code is in the repo, so you're an official contributor! Maybe don't go overboard claiming ownership of the whole project though - expect interviewers to actually look at commit history. If you have a single small commit and pretend like the project is entirely your own work, you'll be easily found out, and it'll be a little embarrassing.