Working With Frameworks

Frameworks are not a panacea for what ails any project. They may speed up development time as you stand on the shoulders of giants, but they could also retard code standards, code reviews, and debugging.

At the same time, failure to properly leverage frameworks can cause the same piece of code to be written and rewritten multiple times, burning hours of work on a problem where a solution already exists.

To balance the pros and cons of frameworks this document demonstrates best practices for working with frameworks at Vokal. The basic rules apply to third-party frameworks and Vokal's own frameworks. Remember, "Lazy developers only use frameworks. Productive developers use frameworks effectively".

Using a framework

Vokal trusts project leads to use the tools and code that work best for their projects. That said, a profusion of frameworks and implementation styles would be difficult to critique and debug.

To use a framework in your project:

1. Fork the framework on GitHub to Vokal
2. Fork the Vokal repository for yourself
3. Add the Vokal repository to your project

When you make changes and improvements to a framework:

1. Commit your changes to your repository
2. Open a pull request from your repository to the Vokal repository on GitHub
3. Complete a code review on your pull request
4. Once the pull request is merged, pull from the Vokal repository to update your submodule for your current project
5. Rest easy knowing you improved the quality of life for everyone at Vokal

You should not make improvements to frameworks in a subclass and you should never solve bugs in a framework with more frameworks. Take ownership of all the code in your project. Treat framework code to the same critical eye you'd turn on your own code and take pride in its quality.

Vokal Frameworks

If you've found yourself writing the same code over and over and over again, it's probably a good time to consider whether that code can be pulled out into a reusable framework from which you and other developers at Vokal (and potentially the OSS community at large) could benefit.

Architecting A Framework

Here are a few guidelines to consider while thinking about creating a framework:

• Talk To Your Team: If you've written something repeatedly, odds are, so have your teammates. Make sure to gather feedback about what should go into a potential framework that the team can use, and try to find potential co-Sponsors for your idea.

• Make It Specific: While it's always tempting to make a kitchen-sink utilities project, remember that it's easier to maintain, update, and test a more focused toolset. Adhere to the Unix Philosophy: Do one thing, and do it well.

• Make It Testable: Wherever possible, add unit tests (and integration tests where appropriate), not only for your own benefit but for the benefit of those using your framework so they can ensure that your code is not what's breaking their app. If possible, add current test status to your README.md file.

• Have Sample Code: Particularly if you are open-sourcing one particular UI Component, have sample code demonstrating its implementation.

• Document Clearly: Make sure that you are writing enough documentation for your component so that if you were, say, abducted by aliens, other developers, both inside and outside of Vokal, will be able to easily understand how your component works.

• Make Any Dependencies Crystal-Clear: Remember that if your code leverages any open-source code or artwork, your code is subject to that code or artwork's license.

Creating And Submitting A New Open-Source Framework

Once you've got an idea for a framework, you can start building it:

1. Find a co-sponsor for your framework. Each framework should have two developers who are responsible for reviewing both internal and third-party pull requests, as well as triaging/prioritizing any bug reports which come in from third parties.

2. Ask a Senior Developer to create an empty, public Vokal repo for that framework.

3. Fork that empty Vokal repo to your own GitHub account as you would any other project.

4. Build out your framework, sample code, and test suite on your fork.

5. Once your work is complete on your fork, submit a pull request to merge everything back to the Vokal fork.

6. Notify the other members of your discipline that you and your co-Sponsor are submitting a new Framework project, and request code review. Please give a timeline for comments of no shorter than three business days to allow all members of your discipline who wish to do so the time to review it.

7. Address any concerns your coworkers may bring up in the feedback phase.

8. Once concerns are addressed, the Senior developer will merge your pull request into the Vokal fork, and the happy little Vokal elves can start using it.

Submitting Updates To Existing Vokal Frameworks

When submitting an update to an existing Vokal repository, determine whether it is Major or Minor:

What Constitutes a Major Update:

• Significant new functionality
• Substantially changed functionality
• Any break in backwards compatibility

What Constitutes A Minor Update:

• Bug fixes not falling under any of the Major Update categories.
• Addition of new documentation, removal of outdated documentation, or clarification of existing documentation.
• Renaming of methods or variables to fix typos or to clarify their meaning.
• Minor new functionality (adding convenience methods, factory methods which simplify object creation, etc.)

Major updates should follow the same process as initial creation of the framework. Allow the rest of your team at least 3 days to give feedback. Each Major update should also receive at least 2 "Good To Pull" comments before it is merged.

Minor updates should follow the standard Vokal code review process of having at least one other developer review your code.

Reviewers of updates submitted as Minor updates have discretion to ask the developer to resubmit their update as a Major update if they feel the change is too significant to constitute a Minor update.

Maintaining a Framework

See Project Maintainers

Licensing

All Vokal frameworks which do not leverage code from another framework requiring a different license should be published under a permissive license. Vokal recommends the highly permissive MIT, BSD 2-clause, or GPLv2 licenses. However, if the sponsors of a particular framework wish to use a license not named here, they may do so at their discretion with the approval of a senior in their discipline.

Good Citizenship

Finally, whether working with Vokal frameworks or third-party frameworks it's important to contribute your changes. First and foremost we should strive to share with those that have shared with us.

Secondly, we do not want to be high and dry if the community around a framework evaporates. Involving yourself in a framework improves your understanding of the framework and empowers you to be self-sufficient.

Take Apple's involvement in Webkit (originally KHTML) and LLVM/Clang as examples. They took over external dependencies, and Apple and the community both benefited from improvements.