Contribution Guide
This is a quick guide on how to actually contribute code to this repository with Atom and Github Desktop. Please try to follow this guide, but of course, there are exceptions. Also, make sure that you've already set up the kits19-cnn repository in Atom and Github Desktop (you can read up more on that in the Getting Started page).
Please raise an issue discussing the problem or suggested enhancement you want to discuss and fix/add. Please assign the proper tag, and if you actually want to commit some code, please reference this issue in those commits or pull request.
The idea is that the master branch is the stable version of the repository and any new changes you make should first be done in this separate branch. Now how should you actually do this?
Here, let's just use the branch io-dev as an example. The idea is that you want to make your branch name as "common sense as possible" so that someone who just started getting into your codebase can easily figure out what the branch is for.
Make your commits in Github Desktop. You'll see your changes and the option to commit to your branch. on the left in the Changes column.
Make your commits as small and as uniform as possible. Ideally, you wouldn't want to be making too many changes in one commit. Also, VERY IMPORTANT: WRITE GOOD COMMIT MESSAGES BY:
- Detailing everything you did
- Why you did it
- How it might conflict with another person's code [situational].
Now, for the most part, you would want your code to be:
- Documented (doc strings, comments)
- Well-written (following DRY [DON'T REPEAT YOURSELF], OOP principles, etc.)
- Tested (ideally through unit tests, but if you really can't, code snippets of interactive code work too)
- either way, NEVER ASSUME. Always assume that something is going to go wrong unless you've tested that it works exactly how you want it to work (exceptions for extreme time constraints)
- Consistent style with the rest of the repository
- This is extremely important in just making the codebase easier to get into. For example, you don't want to write neural networks in both functions and classes. It makes it ambiguous as to how you should actually make your neural networks (deciding between function or class?).
- Reviewed(will address this in the upcoming step)
Great! Now you've finished all your changes and are ready to push your changes to the repository. But wait! You should let other people know what you plan on changing and have others actually review them (to make them better). You would do this in a pull request.
To actually make a pull request, you can just go to the branch you made on the website and you should see an option to create a pull request. After clicking on it, you'll be directed to a page, where you'll describe your changes. Make your title concise and be in-depth about your changes. This repository does not have specific guidelines for what to actually include in your PR descriptions, but ideally, you should at least:
- Include what breaking changes you made
- Include what tiny changes you made
- Why you made the big changes
- Any possible doubts, inquiries or issues.
Remember, the PR IS NOT THE FINAL PRODUCT. You're probably going to be running into a bunch of different issues with your code style, the content, the overall performance, etc. Therefore, please request a contributor to review your code and help you make it better (none of us are perfect):
- Make sure you add the proper tags on the side (Labels, Milestones and Projects). It's just for organization sake, and it could save your ass in the future if you messed up a pull request merge.
- Try to keep your PRs small, but it's on a case-by-case basis.
- Be nice about feedback (USE THE EMOJISSSS)
- Learn markdown for formatting some messages. Here's a nice cheatsheet.
Mention a contributor to actually merge the pull request. If you are a contributor, merge when you get the green light from your contributor reviewer. Feel free to delete the branch if you're not going to be committing code from it anymore. Lastly, feel free to take a break and celebrate!
