7 Adding Features
7.1 Introduction
We typically follow Test Driven Development principles to develop the Workbench, in which a test is written before the main code itself. This way, we can confirm that a bug is fixed once it passes the tests and we have confidence that it will not fail again.
- Open RStudio and switch to the project for the package you are working on
- Checkout a new branch for your feature/bug, e.g.
git checkout -b new-feature - Load package via
devtools::load_all()or ctrl+shift+L ( use cmd on macOS) to load the package NAMESPACE - Document (If needed, either via
devtools::document()or ctrl+shift+D) - Run tests (either via
devtools::test()or ctrl+shift+T to run the entire test suite OR to test a single file, use the “run tests” button in a test file or runtestthat::test_local(filter = '[FILE SLUG]') - Modify tests for new functionality/bug fix
- Add functionality/bug fix with comments
- Run checks with
devtools::check()or ctrl+shift+E
Adding features is an absolute joy in programming because these are little gifts that you can give your users that ultimately serve to make their lives easier and, importantly, give an onramp for more people to enter the community. Here are three short stories about new features and how they affect users.
Story 1: https://xkcd.com/1172/
Story 2: An anecdotal little story about an exchange between a game developer and user:
User: I was designing my character and I noticed that there is no option for it to have a scarf. Can you add that option?
Dev: Sure! I can get that done by tomorrow :)
User: This is awesome, Thank you! I love the new scarf, but I wonder, can it wave a little as I have my character walk?
Dev: Uh… that’s going to take about six months of work.
Story 3: “I joined The Carpentries because I saw that the Workbench was being developed”
7.2 The Workbench user interface is a lesson
When building a feature for the Workbench, it’s important to remember that people who use the Workbench may not know how to use R, Git, or GitHub. They will be working with a lesson and members of The Carpentries who have been here for a hot minute might actually be afraid of rendering a lesson locally from the experiences they had with the Jekyll interface.
7.3 Ask not for whom the feature breaks
Before adding a new feature to The Workbench, it is important to consider the answer to a few questions before even drafting the implementation, which are detailed later in this section. These questions boil down to thinking deeply about purpose, users, support, and resources, which are all interlinked. Broadly, features can be thought of in two categories: non-breaking changes and breaking changes. When given the choice, always strive for the non-breaking change.
7.3.1 Non-breaking changes
Most of the features you will encounter fall into this category. These are little gifts that you give to your users when they update The Workbench. Sometimes, they can be as small as an message that is formatted to be more readable. Often times, they are going to be optional flags in config.yaml that will allow the user to customize their lesson just a little bit.
7.3.2 Breaking changes
For example, the transition to The Workbench represents a feature with breaking changes whose needs outweighed the negative impact for some of the users. This was a project whose purpose was to improve the accessibility and maintainability of our lessons for our community. It would impact the users by providing a better interface at the cost of requiring maintainers to fundamenally change their workflows. We were able to provide support for The Workbench because the developer of the system was a paid staff member of The Carpentries. Finally, the resources existed through funding via Chan-Zuckerberg Initiative, the Moore Foundation, The Sloan Foundation, and The R Consortium. Moreover the tools that we used to build The Workbench were well-tested and well-supported.