-
Notifications
You must be signed in to change notification settings - Fork 39
Contributor's Guide
The Flashbake project welcomes contributors of varying skill sets to help out. We need coders, writers, power users, and anyone else who sees an opportunity to pitch in. Beyond code there is always work to be done on developing our documentation, and we're also looking for people who can help us test new releases.
New contributors should start by checking out our open Issues. Before starting to work on an issue please get in touch with the maintainers to have the issue assigned to you. The easiest way to do that is to write a comment on the issue you're interested in. Similarly, if you have an idea for a new feature that is not a plugin then please discuss your idea with the maintainers by opening an issue. If there's nothing in the issues that feels like a good fit then contact us, tell us a little bit about yourself, and how you'd like to help.
If you're interested in creating a plugin then please create one in your own repository, and share it with others. Flashbake's plugin system is wide open and doesn't require special permission from the project. If, however, you'd like your plugin to be packaged with Flashbake then please discuss this with the maintainers by opening an issue.
The key to working on Flashbake, and any software really, is to change small bits of code at a time, verify that your changes work, commit your changes, and then continue. Whether these small changes should be a single line or an entire file really depends on the complexity of your task. In general, smaller changes are always better.
Here is a basic workflow we recommend while working on Flashbake:
- First, fork the repository on GitHub and then run
git clone [your fork's addresss]to get a local copy. - Create a test Flashbake folder on your system with a
.flashbakeconfiguration file and a hot file for Flashbake to use for commits. See the Wiki for details on configuration. - Next, install Flashbake following the instructions in the Wiki. If you want to use Flashbake regularly, and develop Flashbake on the same system then create a virtual environment for your development work and install Flashbake in there. The easiest way to do this is with the command
/home/your_user_name/test/venv/bin/python setup.py installfrom within the flashbake program folder. The key is to specify installation with the virtual environment's copy of Python to be sure you install it in yourvenv(orenvif you prefer). - Navigate to your test folder and run flashbake in three different ways to verify that it's working:
flashbake -d -v .thenflashbake -c .and finally a full Flashbake run withflashbake .For details on what these flags do see the Running page on the Wiki. - Next, create a new branch that describes whatever your task is such as
git checkout -b fix_feed_plugin - Make one small change at a time, and test that it works by reinstalling Flashbake from your new branch so that the new installation has the small number of new changes.
- If your changes don't raise any errors and work as expected, commit them to your branch, and go to step 9. If you had errors go to step 8.
- If your changes raise an error, then read the last line of the error message. Python failure messages show a traceback with all affected code that raised the issue. In most cases, you only have to read the last line or last two or three lines to find the problem. Real Python has a good explanation of how Python traceback error messages work. If you don't understand why you're getting an error, then copy the error message and search for it online. This will inevitably lead to TONS of Stack Overflow answers. Find one that seems to apply to your situation and try to adapt it to fix your issue. Once you've fixed the error, commit to your branch, and move to step 9.
- If your change doesn't raise an error, then follow the process from step 6 again, and make another small change. Then reinstall Flashbake again with your new changes, run Flashbake to test your changes, commit, and keep going.
This process will ultimately save you time, and it's how we advise all developers to work even with something as seemingly simple as changing a few print statements.
To sum up: Do small changes, test them, and once they work commit the changes to your branch, and then repeat that process until your task is complete.
If you've followed the guide above then by the end of the process you should know that your code works. Before you submit a pull request, please do one final test with all changes committed to be absolutely sure it works as expected.
Once you've submitted your pull request the maintainers may ask if you've tested your changes since we always want to be sure about that before moving on to the next step.
After a pull request is submitted, one of the maintainers will test your code again, and even if it works they may ask for changes for reasons of style, code readability, and so on.
Once everything is sorted out and your pull request has been approved it will be merged into master. This may take a few days after approval so please be patient.
The best way to understand Flashbake's coding style is to look at existing code. If you're writing a new plugin then consult other plugins to see the style they use, as well as to learn the mandatory calls and functions that every plugin needs.
In general, we'd like you to follow the Python Software Foundation's PEP 8 and PEP 257 guidelines. Our goal is to align with the dictum that "code is read much more often than it is written" so make your code readable with descriptive class and function names, and a good amount of comments to guide future developers (including you). Speaking of which, if you're a commenting wizard there is older code in this project that could do with more comments.
Sometimes you can hit a wall before you even get started if Flashbake refuses to work correctly. The first thing to check is your version of Python. Flashbake is built to work with Python 3 and current builds are not compatible with Python 2 so be sure you're installing Flashbake with the latest and greatest versions of Python.
Also be sure that you have python3-setuptools installed, as well as the dependencies listed in our setup.py file, and Git of course.
Next be sure you're running Flashbake correctly and pointing to the target directory/folder. This goes for manual runs, as well as cron jobs. A properly formatted Flashbake command should look like flashbake ~/Documents/flashbake_test/ or if you're already in the test directory then flashbake .
While we strive to make Flashbake compatible with everything that has a *nix shell there can be occasional problems with special projects such as WSL on Windows. If you do run into a problem with WSL or any other Unix-y system please let us know.
Flashbake uses several issue labels to help guide our work: bug, good first issue, enhancement, and release milestone. All of them are fairly self-explanatory.
Bug is for problematic or unexpected behaviors from Flashbake, and issues labeled with bug are considered high priority.
The good first issue label is an excellent way to identify issues aimed at first-time contributors.
Enhancement identifies ways to extend the usefulness of Flashbake by adding a new feature or adding to the functionality of existing features.
Finally, a release milestone is an issue that needs to get done before we can release the next, great version of Flashbake.
If you've read this far, what are you waiting for? Roll up your sleeves, jump into the issues, and join our community!