This project is currently open to contributions. In fact, we encourage anyone and everyone to contribute! That's what makes open source awesome!
If you'd like to contribute, check out the currently open issues. Generally those are available for anyone to tackle. If there's something else you'd like to contribute, create an issue for what you would like to add. We are very open to adding new features/docs!
- Setting Up Your Dev Environment
- Doc Changes
- General Non-Doc Contribution Flow
- Running Tests
- Getting Credit for Your Contributions
You will need to have the following installed on your machine before continuing:
- Node >= 6, installation instructions
- NPM >= 3, installation instructions
- Yarn, installation instructions
Next, you'll want to cd into the project's root and install our node dependencies:
cd iwanttocontribute
yarn installNote: This app is now officially using Yarn for it's package manager. Make sure you check out the installation information above.
The last requirement is that you have a Github access token created. This is required because the Github API allows us a much larger rate limit when accessing their API with an authenticated access token. To create your access token, follow the Creating a Token part of this guide. Give it whatever descriptive name you want, and as far as permissions go, don't give it any additional permissions (ie. don't check the checkboxes). There's no need. This token only needs public access level.
From here, the token (a long string of characters) should be displayed to you. Copy the token, create a file named .env in this project's root and add this line to it:
GITHUB_TOKEN=<Your Github Token>
(make sure you replace <Your Github Token> with the token you copied). Save that file, and make sure you DON'T commit it to git! This is your personal secret Github token.
Voila! Your dev environment is all set up! You can now run yarn start to spin up your development server, which will redirect you to the app in your browser.
Note: For more information about the dev environment for this project, along with some other related topics, check out the Developer Guide in the docs.
Using the default ubuntu/trusty64 should work fine. You will need to forward a port to access the app from your local machine. Add this line to your Vagrantfile:
config.vm.network "forwarded_port", guest: 3000, host: 3000
You should now be able to access your app now at http://localhost:3000
This project should include detailed docs about tools, methodologies, and approaches that are used within this application. This will serve as a good place for others to learn, but solidify the knowledge of these things to the doc authors.
When making doc changes, we want to use relative URL paths for references to other docs, but full url paths for references to source code files.
Examples:
Referencing to doc files, use a relative URL path like: [create-react-app-readme](docs/create-react-app-readme.md).
Referencing source code files, use a full url path like: [SearchBar.jsx](https://github.com/tmobaird/i-want-to-contribute/blob/master/src/components/SearchBar.jsx).
The doc book for this project currently lives as a GitBook here. All doc files should be optimized for GitBook, using normal Markdown Syntax (Markdown Cheat Sheet).
- Make sure the change you want to make has an issue related to it. If it doesn't, feel free to create one!
- Fork the repo to your namespace and set up your development environment.
- Perform a
git checkoutand checkout a branch named something that is related to the change you are making. Some examples are:feature-adding-search-filtersfix-catching-search-errordocs-react-redux
- Make the desired code changes in your favorite editor and commit your changes!
- Write tests for the code you've added (or make sure tests exist for the code you wrote).
- If you don't know how to write tests with Jest, don't worry! Push up the code and create a pull request to the main repo. A maintainer will help your write tests for your newly added code. We all have to start somewhere!
- Squash commits
- This is not always necessary, but if you found yourself making a bunch of commits with your changes (some of which aren't of much value), squash them.
- If you aren't familiar with commit squashing, check out this.
- If all the tests pass, push your commits up to your fork.
- Create a pull request from your forked repo to the main repo.
- Wait until a maintainer views your awesome changes! (We'll try to do this as quickly as possible)
To run your tests locally, you can simply run:
yarn test
That will run your tests and start a test watch mode, which means every time you save a file, it will re-run your tests.
More information about testing for this project can be found here.
And some other helpful resources:
Since this project is all about helping people contribute to open source projects, we love to show off the awesome people that have helped out with this app. To do that, we have two different docs/files that include information about our contributors and the places they are from!
CONTRIBUTORS.md is a simple markdown doc that includes a list of locations around the world with a list of contributors from those locations.
contributors.json is almost the same as the markdown doc, but is a JSON data set. Essentially it is just an Object with the attribute locations that consists of an array of location objects that include basic location information as well as an array of contributors.
When adding a new location in either of these files feel free to add them by city, state, or even country! It's entirely up to you! Also if you'd like to get credit for your work in this fashion without disclosing your location, feel free to add an anonymous location to these lists. It's awesome to track our contributors' locations, but if you don't feel comfortable disclosing that information, there should be no pressure to include that!
Here's what our live Contributors Map currently looks like!
If your location exists, simply add a new bullet to that section with your name followed by your Github username as a link to your Github profile. Example:
- Thomas Baird (@tmobaird)
Raw Markdown:
- Thomas Baird ([@tmobaird](https://github.com/tmobaird))If your location does not exist on the list, feel free to add it! If there's any emoji you can think of that is appropriate for your location, feel free to add that as well! Example:
- Thomas Baird (@tmobaird)
Raw Markdown:
### Virginia :emoji_name:
- Thomas Baird ([@tmobaird](https://github.com/tmobaird))The contributors.json data set is a JSON object that includes the property locations which is an array of locations for all the places our contributors come from. Each location has a set of properties, those being:
- name
<String> - emoji
<String> - latitude
<Number> - longitude
<Number> - contributors
<Array>
An example JSON object for a location looks something like:
{
"name": "Virginia",
"emoji": "icecream",
"latitude": 37.4316,
"longitude": -78.6569,
"contributors": []
}When creating a new location, make sure you include the longitude and latitude of this location (this is what allows us to place markers on our map in these locations). In regards to these values, north (latitude) and east (longitude) coordinates should always be positive values, whereas south (latitude) and west (longitude) should always be negative values. Example:
Virginia: 37.4316° N, 78.6569° W -> latitude: 37.4316, longitude: -78.6569
When adding yourself as a contributor to a location, add a new contributor object to that location's contributors array. A contributor has the following properties:
- name
<String>: This is your name (ex. Thomas Baird) - username
<String>: This is your github username handle (ex. tmobaird)
An example contributor object should look something as follows:
{
"name": "Thomas Baird",
"username": "tmobaird"
}If anything about this process of adding yourself to the contributors lists was hard to understand, feel free to create a Github issue for clarification or post a message for help in our Gitter channel here:
