Submitting Work
Instructions on how to submit your contributions.
We've come up with several approaches to submitting contributions, organised by expected technical proficiency, and the type of contributor.
Writers
We've come up with several ways to contribute articles, with varying levels of technical difficulty in mind. We're still working on making this easier, so you can expect that we'll update this section soon!
This is the most complex approach. We only recommend it if you have lots of experience working with computers.
- Install Git by following these instructions.
- Create a GitHub account if you haven't already.
- Create an SSH key and add it to your GitHub account by following these instructions.
- Go to the site repository.
- Click/tap the Fork button at the top-right of the page.
- Select an owner and repository name if the default settings aren't satisfactory.
- Click/tap the Code button at the top-right of your fork's page.
- Ensure you have the SSH tab selected, and copy the provided URL.
- Use Git to clone your repository by opening a terminal and
using the
git clonecommand. - Use a text editor (such as VS Code) to create your article file in
/src/articlesas described earlier. - Work on your article, using the structure described earlier.
- Use Git to commit your changes by opening a terminal and
using the
git commitcommand. - Use Git to push your changes to GitHub by opening a terminal and
using the
git pushcommand. - On GitHub, navigate to your fork, and click/tap the Compare & pull request button.
- When prompted, provide a title and description for your pull request.
- Click/tap the Create Pull Request button. If your article is not ready for review yet, click/tap the Create Draft Pull Request button instead.
- A Cloudflare bot should leave a comment on your Pull Request with a link you can click to preview the site with your changes.
- Continue working on your article as needed. Your Pull Request will automatically update as you push commits to your fork.
- Keep an eye on your Pull Request, and address any comments and reviews people make.
- When everyone's happy with your article, we'll merge your Pull Request. It will be available on the site shortly after.
Instead of working directly on your computer, GitHub provides a way to use the VS Code editor in your browser. This is less complex than the previous approach, but still requires intermediate computer experience.
- Create a GitHub account if you haven't already.
- Go to the site repository.
- Click/tap the Fork button at the top-right of the page.
- Select an owner and repository name if the default settings aren't satisfactory.
- Once your fork is ready, press
.on your keyboard, or edit the URL in your address bar, replacinggithub.comwithgithub.dev. - Install the recommended plugins if the editor prompts you to do so.
- Under the Explorer tab on the left, navigate to
src/articles. - Right-click the
articlesfolder, and select New File.... - Name your article file and hit
Enter. - Work on your article, using the structure described earlier.
- Under the Source Control tab on the left, type a commit message and hit
Ctrl+Enter. - On GitHub, navigate to your fork and Click/tap the Create Pull Request button. If your article is not ready for review yet, click/tap the Create Draft Pull Request button instead.
- A Cloudflare bot should leave a comment on your Pull Request with a link you can click to preview the site with your changes.
- Continue working on your article as needed. Your Pull Request will automatically update as you push commits to your fork.
- Keep an eye on your Pull Request, and address any comments and reviews people make.
- When everyone's happy with your article, we'll merge your Pull Request. It will be available on the site shortly after.
This method allows you to edit your article directly on GitHub. However, the basic editor lacks many useful features, and we don't recommend this approach unless it is your only option.
Create a GitHub account if you haven't already.
Go to the site repository.
Click/tap the Fork button at the top-right of the page.
Select an owner and repository name if the default settings aren't satisfactory.
Once your fork is ready, navigate to
/src/articles.Click/tap the Add file button at the top-right of the page, and select Create new file.
Name your file as described in the previous section.
Work on your article, using the structure described in the next section.
Click/tap on the Commit changes... button.
In the popup that appears, click/tap on the Commit changes button.
Navigate back to your fork's main page and Click/tap the Create Pull Request button. If your article is not ready for review yet, click/tap the Create Draft Pull Request button instead.
A Cloudflare bot should leave a comment on your Pull Request with a link you can click to preview the site with your changes.
Continue working on your article as needed, by navigating to the article file and clicking/tapping on the button that looks like this:
Your Pull Request will automatically update as you push commits to your fork.
Keep an eye on your Pull Request, and address any comments and reviews people make.
When everyone's happy with your article, we'll merge your Pull Request. It will be available on the site shortly after.
If you'd prefer to avoid using Git or GitHub directly, you may submit your articles to us on Discord. However, as of this writing, we only provide this option to Community Management Community members. Information on how you join us will be provided later.
- Create a post in the #article-submissions forum channel, being sure to follow the posting guidelines.
- Feel free to use your post to gather research and chat with other members about your article.
- At some point, we'll assign a member of staff to your submission. They will review your submission and help you work on it, providing feedback and support.
- When your article is ready to be contributed, your assigned staff member will create a Pull Request on your behalf. You will be responsible for monitoring this Pull Request for comments and reviews.
- You may submit updates to your Pull Request via your assigned staff member.
- When everyone's happy with your article, we'll merge the Pull Request. It will be available on the site shortly after.
Developers
We recommend the following workflow to anyone that wishes to contribute as a developer:
- Start by forking the site's repository.
- Browse the issues and Pull Requests to ensure you aren't duplicating someone else's work.
- If an issue exists regarding what you'd like to contribute, leave a comment on it so that others know you're working
on it.
- Otherwise, create an issue and mention that you're handling the task. This is especially important for work our staff team hasn't signed off on yet — don't open a Pull Request if you haven't talked with us, otherwise you may end up doing work we ultimately decide not to accept.
- Create a new branch on your fork to encapsulate your work.
This is important as it allows you to more easily update the
mainbranch in your fork whenever we make changes, and it means you can manage multiple Pull Requests at the same time if you'd like. - Start making changes! Remember to test that everything works, and especially ensure that everything looks good at every Tailwind breakpoint.
- Once you've pushed at least one commit, open your Pull Request. It is important to open your Pull Request early, so you can receive feedback as you work. If you're not ready to receive feedback yet, mark the Pull Request as a [draft(https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests)].
- Once your Pull Request is ready for feedback, mark it as ready for review.
- Keep an eye on your Pull Request, and ensure that you address and respond to any reviews and comments.
- Once everyone's happy with your Pull Request, we'll merge it. Your changes should appear on the site within 5–10 minutes.