Welcome open-source user! We're glad to have you here. You're probably interested in contributing to our open-source repositories here at Bit Project. Before we go over the standards of contributing to our repos, let's go over few key points to help you get started.
Here's a checklist of items with topics you should be familiar with to successfully contribute. We'll be going over all of these concepts, so head to a specific section if you need help there.
- Github (Issues, Pull Requests, Commits and Forking Repos)
- Markdown Syntax and Files
- How Bitcamps work!
If you have some knowledge of Github (example: what an issue is, forking, creating a pull request) then feel free to skip this part. If not, here is a quick summary of some important terms and a few helpful links if you're just starting with Github.
| Term | Meaning |
|---|---|
| Issue | Issues are a great way to keep track of tasks, enhancements, and bugs for your projects. They’re kind of like email—except they can be shared and discussed with the rest of your team. Most software projects have a bug tracker of some kind. GitHub’s tracker is called Issues, and has its own section in every repository. |
| Forking | Forking in GitHub is a process of creating a copy of a complete repository to the user’s GitHub Account from another account. When a user forks a repository, all the files in the repository are automatically copied to the user’s account on GitHub and it feels like the user’s own repository. |
| Pull Request | A pull request in GitHub is a request to the maintainer of a repository to pull in some code. When you write some code that you want to contribute to a repository, you create and submit a pull request. Your code contains some proposed changes to the target repository. |
| Repository | Just like a repository on Git is a Git repository. A repository is similar to a folder and a GitHub repository becomes a folder that is available online on the cloud for the people to download, access and contribute. This folder contains the code files of the project which can now be used by the other people. |
| Committing | If you commit a file, you are essentially saving it in your repository. Every time you make changes and press "commit," you are creating a new log in Github that records the changes you made. It's kind of like taking a picture of the repository at the time you commit! |
If you still feel like you don't completely understand how Github works, check out these helpful links:
- Github Basics (Learning Lab): https://lab.github.com/githubtraining/introduction-to-github
- How Issues Work (Github Guides): https://guides.github.com/features/issues/
- Contributing to Repos (Youtube Video): https://www.youtube.com/watch?v=waEb2c9NDL8
This is a markup language that allows you to create formatted text with a plain-text editor. Surrounding text like **this** makes it bold. Surrounding text like *this* makes it italicized. You can even link websites and images! That's why a lot of the raw files will have a lot of symbols. Check out a cheatsheet here.
Remember: it's important to format anything you contribute. Nobody wants to try to decipher long blocks of text!
You might want to get familiar with how Bitcamps work before trying to make your first contribution, or else the content may appear confusing. There are 3 basic components for curriculum in each Bitcamp:
- Homework: This is typically a Github Learning Lab that walks students through a course.
- Livestreams: Our camp mentors stream live on Twitch to expose students to the curriculum.
- Final Project: This is the most exciting part of Bitcamps - an open-ended project with which students showcase their new skills!
Now it's time to start contributing! At this point, you should have a decent introduction to the basics of contributing Bit Project Style.
When it comes to picking which issue you want to work on, it all depends on a two key aspects: the level of difficulty and availability.
Difficulty : When viewing all open issues, finding the difficulty of the issue will be based on whether the issue is labelled with "newcomer" or "good first issue". If the issue you want to contribute to isn't labelled with said newcomer labels, it is most likely more difficult then simply a small text/code error.
Availability : When viewing all open issues, availability will be based on whether the issue is closed or open, and whether the issue has been assigned to a Bit Project member. If the issue is assigned, it means the issue is not for open-source users. If you view an issue that is open and unassigned, feel free to contribute to it!
These are our repository specific labels (these are super important for issues). These labels communicate to other open-source contributors like you what the specific problem is and how they should address it.
| Term | Meaning |
|---|---|
| Bug | When an issue is labelled as a bug, there is an issue within the given file/folder. This could be a typo in the code or markdown file or even mean there is still a missing part to a repository that needs to be added. |
| Documentation | When an issue is labelled as documentation, there is an issue within the markdown file of the given folder/repository. This could be a typo in the repository documentation or even mean a part needs to be created or added to complete the documentation fully. |
| Newcomer | When an issue is labelled as newcomer, the issue is for new users who don't have as much experience with Github or open-source contributions in general. Usually these issues will be much easier tasks like fixing typing errors, code errors, and more. |
| Specifics (example: slack, serverless, etc) | When an issue is labeled with specifics, the issue is focused on a certain Bit Camp. While these labels don't change the difficulty or type of issue, they are used to specify which course the issue is targetted towards. |
If you're ready to start contributing content and have picked your issue, here are your steps you should take:
- Fork the bitprj/BitCamp repository.
- Make your first commits!
- Start a pull request while your contribution is still a draft
- Refer to this for more detailed information.
- Title your pull request with something relevant and specific
- Write at least one sentence to describe what you are contributing
- In the same description box, add
closes #xx(thexxis the issue number you are addressing). This links the issue to your pull request! - Make your pull request marked as a "draft"
- Make some comments on your PR: need feedback? Not sure about something?
- Continue committing to your forked repository.
- Remove the "draft" mark once you're done and ready for someone to review!