First and foremost, thanks for considering contribution here at Parabeac Core!
Below you'll find a set of guidelines around how to contribute here at Parabeac. These aren't rules set in stone, feel free to use your best guidance, and if you have any ideas feel to make a Pull Request and suggest changes. We've also created an updated Getting started with Contribution Guide on our wiki which we recommend for a brief overview and introduction to contributing here on Parabeac-Core.
Table Of Contents
Everything and everyone within this project is governed by the Parabeac Code Of Conduct. By participating in this project you are expected to follow this code. If there are any questions or you see any unacceptable behavior please contact [email protected].
Parabeac Core(or PBCore) is the tool that translates design files to flutter code. We do this by reading through the complex design file inner-workings to convert the UI elements within the design file to the appropriate Flutter Widgets. You can use this tool via our cli.
We would rather be great at one thing than mediocre at many. With that mentality in mind we designed Parabeac Core to export code that not only can be used but also makes sense from the developer perspective. This aligns with our commitment to ensure developers have the most flexibility with the code they export, which is where Parabeac Eggs comes in. Parabeac Eggs, our name for custom defined Plug-ins, allow developers to define their own code exports and allow designers to be even more specific with the way they define the elements PBCore generates.
We've divided the code conversion and export process into 3 key phases:
- Design Phase (Parabeac Design Protocol & Parabeac Design Language)
- Conversion Phase (Parabeac Interpretation Engine)
- Exportation Phase (Parabeac Generation Service)
First, in the Design Phase, designers build their UI/UX elements within the design language of their choice (at the moment we only support sketch but have plans to shortly support other platforms like Figma). From here Designers can use the Parabeac Design Protocol to denote the elements they would like PBCore to generate. After the designs are ready to be converted they are handed to PBCore where we're able to convert the platform specific files into our intermediate design language: PBDL.
Next, in the Conversion Phase, the newly created PBDL code is sent to the Parabeac Interpretation Engine within PBCore. This then works to convert the PBDL into Parabeac Intermediate Nodes, the last form it will take before becoming Flutter Code. The Interpretation Engine is divided into the following three primary services:
- Parabeac Visual Service
- Parabeac Layout Service
- Parabeac Alignment Service These services work in tandem to create the correct code structure before the elements are generated as Flutter Project. To learn more about these services inner workings look here.
Finally, in the Generation Phase, the Parabeac Intermediate Nodes are then converted into their final form: the Flutter Code. It is here that all the work put together over the last 2 Phases culminates into the final product as the generation service takes the correctly formatted Parabeac Intermediate Nodes and uses them to create the appropriate widgets.
With a clear picture of how each of the different phases within the Parabeac Export Process works let's take a look at what it takes to run Parabeac Core on your machine.
You'll need the following tools to run Parabeac Core, as well as a text editor or IDE of your choice (we recommend Visual Studio Code with the Dart and Flutter Extensions)
- Git
- Dart
- Install latest version (If using Visual Studio Code simply install the Dart Extension)
- Flutter Latest version
- Install latest version (If using Visual Studio Code simply install the Dart Extension)
- node.js
- node.js is needed in order to run the Sketch-Asset-Converter.
Follow these steps in order to run PBCore on your local environment:
- Clone PBCore repo in order to get the code on your machine
- If you have any plugins make sure to put the plugins in the plugin folder
- In your terminal change directory to the root PBCore directory and run:
$dart parabeac.dart -p <Absolute Path To Design File> -n <ProjectName> And your done! Keep an eye on the terminal and your flutter project should ready to use in only a few moments.
When filing an issue please make sure to have the most up to date version of parabeac core installed. Please see our FAQ Page for some of the larger known issues.
When filing an issue with Parabeac Core please follow these steps so we can resolve the problem as quickly as possible
- Check the Issues section of our GitHub for any issues with the tag "bug" or "breaking issue" to make sure there isn't already an issue encompassing this problem thats already filed.
- Please include the Parabeac Core version, link to Design File, and Code Exportation Snippet with Error Code (if applicable) within the issue.
- Post said issue to our GitHub Issues section with the above stated information.
- Please make sure to include as much detail as possible so we can replicate the problem and find a solution as quickly as we can.
- Keep an eye on any updates as we will try and get in touch with you as soon as possible.
While we're dedicated to our community we are always looking at ways to improve our tool and tech. Feel free to leave suggestions that you would like to see in the future, we're constantly working to improve our process and make things easier going forward.
When looking to contribute there are a few simple steps you can follow to make sure the work you do is prioritized and beneficial to Parabeac-Core. The following Process is how we manage the contribution flow here at Parabeac:
- Fork the Repository on Github.
- Check the issues section on Github to see if an issue has already been made for the work to be completed:
- If it has, reach out to whoever was assigned said issue or, if that issue is not assigned to anyone contact us in the #dev_questions or #parabeac_hackers channels on our Discord to discuss taking the issue.
- If it has not, verify that the work is non-trivial and then create an issue on our Github issues section, make sure to reach out to the Team on Discord if this issue is pressing. You can put the tag proposal on the work you’re trying to do to help us identify and help with prioritization.
- Create a branch off of the dev branch (if the issue is non-breaking) or the stable branch (if the issue is breaking) within your fork of the repo and implement your changes. Make sure to reach out to someone with the “Team” Role on our Discord to discuss your changes or ideas if you have any questions.
- Make sure the tests pass. We have a set of both integration and unit tests created to insure that changes made to the Parabeac Core Repository are stable and consistent with the rest of the project. With this in mind if you're adding new code or changing things you'll likely need to add a new test to accomodate your changes. When your asking yourself "Do I need to write a test for this" the answer will almost always be a yes.
- Submit this branch to the repo as a Pull Request. For Details on how to run our testing suite please see below.
- Undergo code review. These reviews usually take the form of comments either on the PR on GitHub or within the Parabeac Core Discord. More often than not a Parabeac Team Member or Committer will respond or comment to your PR within about 48 hours. If you haven’t heard from anyone by that time feel free to poke anyone on the Parabeac Team on our Discord (But especially our CEO @SiliconIvan).
Once you have the appropriate sign offs, your final reviewer should merge your code but if they haven’t feel free to merge it in.
While following these steps should you have any issues don’t hesitate to reach out to anyone on Team Parabeac on our Discord
We prioritize keeping the tree clean and keeping releases stable above all else. Pushing out new features is great, but pushing out new features that also don't break existing features is even better.
We have two separate forms of tests within our test suite: Unit Tests and Integration Tests. If you are writing in new functions and expanding on existing feature-sets you'll need to write the appropriate unit tests for your changes to ensure they aren't broken by later changes. If you're adding in new modules or adding entire feature-sets you'll need to not only write the unit tests for these features but also write integration tests between your module and and any modules it interacts with. For any help or further information please check out the #dev_questions channel on our Discord.
Running the Test Suite:
To run the test suite for parabeac core you just need to run pub run test in the root directory of Parabeac core. However, if you also plan to test for Figma Files as well as sketch files you'll also need to add an environment variable called FIG_API_KEY to your environment with your API Key. Running the command export FIG_API_KEY = <key_here> in your terminal or adding that command to your .zshrc/.bashrc files will allow the testing harness to run all tests including those for Figma files as well.
Pull Requests are how you bring the work you’ve done back into the Parabeac-Core codebase. By submitting a Pull Request (or PR) you’re able to merge the changes you've made on your own branch into either dev or stable(Depending on the work done). All PR’s must be reviewed before they can be merged into the codebase in order to ensure that the work being done follows our guidelines and does what it says it will. Code review is usually done within Github itself but in special cases with complex work we do recommend talking with the team directly in our Discord. For Additional insight, check out or Tree Hygiene Page on our Wiki!
Contribution is the best way to make sure Parabeac Core keeps driving forward to its fullest potential and your contributions are the best way to get us there.
At Parabeac we wanted to make sure developers could create plugins that changed the way code would be exported. To do this we built our tool to take in semantics that override the way Parabeac normally treats these elements. By creating an egg, developers can add new semantics and choose how those semantics are converted into code during the generation process. This allows for the most specific code generation without putting a large amount of work and hassle on the designers.
To get started with Parabeac Eggs check out our Parabeac Egg Template or check out our git-based marketplace for templates.