How to get onboarded to a project asynchronously, without having to communicate directly with the maintainers of the project. This was possible because:
- Clear contributing guidelines makes it easy to figure out how to contribute effectively to the project.
- Clean project structure and code makes it easy to figure out how the product works, and by extension how to work on the codebase.
How to easily find issues to work on for OSS projects. This was possible because:
- Good and concise tags that describe the issue (e.g. bug or feature request) which helps contributors to quickly identify the issues that interest them.
- Maintainers provide an estimated difficulty level, so that contributors can determine whether the issue is likely to be workable for them based on their own familarity with the codebase.
- Intentionally creating/leaving a trivial issue for new contributors to work on helps to encourage potential new contributors to get started with the codebase without being too intimidated by harder issues.
Communication between users, contributors and maintainers can remain straightforward and effective even if it is completely asynchronous. This is helped by using the appropriate medium for different types of communication:
- Persistent and crowdsourced issues (e.g. feature requests, bug reports) are communicated via the GitHub issue tracker. This is an effective way for users/contributors to share information that may be useful to the rest of the community.
- More general, maintainer driven ideas (e.g. product roadmap and design documents) are communicated via more centralized mediums such as Google Docs, Markdown documents on GitHub, and the project blog which is more suitable for longer documents.
- More short-lived conversations, where information shared is more self-contained and does not need to be shared with the broader pool of users or contributors (e.g. help getting started) can be held in the Discord channel.

Development

How to organize code in a way that is easily readable and extensible:
- The Docusaurus codebase makes heavy use of abstractions. Most components, methods, and even files are relatively short. By containing only as much logic in each abstraction as necessary, the codebase becomes significantly easier to read and reason about.
- Good, descriptive variable names are essential for understandable code. Some useful conventions: method names should start with a verb, and variable names should be nouns that describe the content and intended use of the variable.
- Opt for readability over conciseness, especially for complex boolean statements (e.g. !link.languages && !link.search is harder to understand than !(link.languages || link.search)).
- Sometimes, using mutatable variables (sparingly!) can help improve code readability, and avoid having too many variable names that need to be kept track of.
Using good tooling can improve developer productivity:
- Using a good code formatter (Prettier in this case) allowed the project to retain a consistent coding style despite having multiple authors working on it. Contributors did not have to worry about how the code was formatted, which reduced a lot of friction in the review process, as well as cognitive overhead when writing the code.
- Using a test framework that supports component-level snapshot testing (Jest) allowed tests to be easier to write and maintain by reducing the scope of each individual test case.

Product

A clear product vision helps to align the expectations and goals of both users and developers (though this may sound trivial, I feel that these traits are crucial to building and growing a strong community surrounding the project and allow it to grow):
- The clearly stated aim for Docusarus to facilitate "easily building, deploying, and maintaining open source project websites" - which gives users and developers a clear idea of what to expect from the product. This is not only useful for the core maintainers to decide what features to work on along with their priority, but also for other contributors to feel confident in the long-term vision of the product they are working on.
- Similarly, offering a product roadmap gives users and contributors a sense of how the project will evolve. This can help get buy-in from users by helping them to decide if it is the right project for their use case. For developers, this can give them a better idea of what kind of work they might be doing should they decide to be a long-term contributor to the project.

Suggestions for Internal Project

Write (good!) contributing resources
- As the MarkBind team changes with every CS3281/2 batch, it is essential for the project to be accessible to new contributors. It would be more productive if each new batch is able to onboard themselves to the project with minimal guidance from senior developers.
- Furthermore, if MarkBind is to grow as an OSS project, it would be necessary for external contributors to get involved. Without contributing documentation, external contributors may be less willing to get started working on the project.
Improve abstractions in the codebase
- The current codebase has several massive files and methods (e.g. Site.js and Page.js) and some really complex methods (e.g. parser.js) that are difficult to understand, and even harder to maintain or extend.
- Breaking these down into more layers of abstraction can help improve readability, as well as code reuse.
Offer a more real-time form of communication
- At the moment, all communication with external parties (both contributors and users) is done via either email or the GitHub issue tracker. While this is good for slower-paced discussions, it is not very effective for quick conversations.
- Having an alternate channel for such discussions (e.g. Discord, IRC, Telegram) could be useful for new users or contributors to get quick responses for the issues they face. The quicker responses via these channels might be important to drive adoption of MarkBind in an already crowded space.
Have a clearly stated product vision and roadmap
- Though there is a product vision that is shared internally (to be the best site for documentation websites), this vision is not shared with the public.
- By clearly stating the product vision, external users and contributors are able to more clearly assess if the project suits their use case, and help generate buy-in from these parties.
Better Tooling
- Adopting a code formatter could improve developer productivity by standardizing the formatting of the codebase. Though there are challenges in adopting a formatting tool in an existing project, I feel that finding the right tool/configurations for this is worth the initial effort and inconvenience getting used to a different formatting style as it really helps improve consistency and productivity - especially as the size of the team grows.
- Using Jest's snapshot testing to test the HTML output from individual Markdown snippets can allow user-facing features (e.g. include) to be easily unit tested without having to rely solely on system tests. This can be helpful in identifying regressions more effectively than examining potentially large diffs generated by our existing system tests.
Use a Javascript UI library
- At the moment, large parts of the site's HTML is generated by a combination of EJS templates, a Vue component library, and plenty of raw string handling.
- This can be rather unwieldy at times, and having several different entry points to changing the output of the site makes the rendering process unnecessarily complex and difficult to understand.
- We might want to consider how this can be avoided by using a single Javascript UI library (e.g. Vue or React) to handle all of the HTML generation. This would allow us to use one consistent layer of abstraction to deal with all HTML generation logic.
- This would require an overhaul of large portions of the existing logic - which might not be the best idea. Perhaps this is something that might be considered for future iterations of MarkBind.

Suggestions for External Project

Use System Tests:
- At the moment, automated tests for the project are limited to unit tests. Most system level tests (e.g. how the entire site looks) requires manual testing.
- Using automated system tests to create a snapshot of a sample test site (similar to MarkBind) could help to automate this process and prevent regressions that are not detectable by the unit tests.

LIN SI JIE

Project: PHPMyAdmin

My contributions:

Introduction

PHPMyAdmin is an open-sourced web interface for MySQL and MariaDB. As a portable web application written primarily in PHP, it has become one of the most popular MySQL administration tools, especially for web hosting services. I chose to contribute to PHPMyAdmin because it is one of the first tools I have ever used when I first learnt Web Development, and it would be meaningful for me to contribute back to the tool that has served me well for many years. Furthermore, given its large user base and nature of operations, it is important for PHPMyAdmin to engineer a reliable and secure product. This is where I had hoped to learn best reliability and security practices and apply them to my own projects. I am also very comfortable with the language, having used PHP primarily prior to picking up more recent languages like NodeJS.

Key takeaways

The PHPMyAdmin community has a similar process to many of the projects I've worked on, yet there are many small details that pondered reflection.

#1 In very large projects, it is important to write code in a clean manner. PHPMyAdmin uses automatic tools to check for code quality and style. In addition, there is strong emphasis on writing code in classes. The nature of the underlying language, PHP, is not very OOP-focused. However, PHPMyAdmin uses many classes (e.g. forms, databases, tables etc) to abstract and simplify implementation. There is also strong evidence of reuse: constant strings, form generators, database abstractions that break down the code into much more manageable chunks. Even as a new developer, I had little trouble diving into PHPMyAdmin to fix bugs and add checks because it is easy to trace and understand the role of each function and each class.

In contrast to my projects, SE-EDU: AB4's code is extremely clean and each function has its own dedicated role. With a core focus on developing as a model for teaching Software Engineering, AB4 focuses on writing our code to strictly follow OOP guidelines. However, I wonder if there is over-engineering in AB4. In PHPMyAdmin, there is a strong sense of structure - each class does its own unique role. However, things like single responsibility principle are not as strictly enforced. While these principles seem to make code cleaner, we must also remember that if the role of each function is so small, it takes more effort for a developer to trace through the code and to have a global picture of the flow in the program.

MarkBind: MarkBind's code is certainly less clean than PHPMyAdmin. Even after 10 weeks of developin in MarkBind, I still have to repeatedly trace through code to understand the process. Sometimes, I need to even consult senior developers to understand how MarkBind simply "magically" works. This is a sign that MarkBind would need more emphasis on code maintainability. Perhaps we need to rewrite some of our functions and features as smaller, more cohesive classes.

#2 Commit messages should be descriptive, but not overly complex.

As with most Software Engineering project, high quality commit messages are a key part of Open Source Software. Commit messages allow future developers to understand why certain design decisions were made, providing a snapshot in history to make changes based on. PHPMyAdmin is no different - every commit needs a corresponding descriptive commit message explaining the change.

However, this commit message "rule" is also not strictly enforced. While I try to provide convincing reasons behind the need for each commit, some developers see less point in writing a descriptive commit message. It appears that these commits are merged anyway.

My experience at SE-EDU has trained me to write highly descriptive commit messages that served to convince maintainers the reason behind every commit. This is in stark contrast to commits at PHPMyAdmin or MarkBind, where developers simply need to provide a descpriton of their commit. For PHPMyAdmin, developers can even sometimes get away without writing significant commit messages. This has prompted me to reflect on why SE-EDU has adopted such a requirement for commit messages. On one hand, these messages explain commits so well that the project can be easily understood by anyone. This gives the maintainers confidence that the authored PR is correct. On the other hand, such a system slows down development. Given that every commit needs to be tightly scoped and must accompany such an extensive commit message, the impedence to change is very high and developement cycles are slow. Perhaps, for an average Software Engineering project, a system similar to that of MarkBind would be ideal. While there is no fixed format and fixed requirement, developers are required to write messages that are informative and descriptive. Such an option finds a middle ground that balances ease of development and quality.

#3 It may not be feasible to enforce good SE practices when a project grows large.

The key driving component behind every Open Source Software is the quality of its commits. Like every other OSS, PhpMyAdmin uses CI tools to automate the process of code checking. This process is similar to my other projects: MarkBind and SE-EDU where we use CI extensively to do testing.

I notice that while tests play an important role in PhpMyAdmin (some are necessary to assure functionality, others important for security), the test coverage is surprisingly low at 52%. This could perhaps be due to the fact that PhpMyAdmin has so many contributors (almost 1000) and PRs on a daily basis. Having strict requirements for testing meant that it would be heavily resource intensive to ensure that new PRs are done properly with tests. In addition, this might also mean sacrificing development speed. This might further delay the release cycle and ability for the organisation to respond quickly to fixes and other updates. Being a long-time legacy project of 20 years, PhpMyAdmin started during an era where idea of testing has not yet been popular, contributing to its current poor coverage.

I wonder if it's necessary to sacrifice "proper" software engineering practices if we want our project to expand in scale or to hasten the development process. For example, the high quality required by SE-EDU means that commits go through extensive revisions, small changes need to be accompanied by high overhead like commit messages, tests and documentation. The high impedence to change means that some developers could potentially avoid contributing because of the hassle. At the end of the day, it is the project that determines the its own priority. Then projects that focus and require reliability and quality would certainly place greater emphasis on them, mandating tests and proper coding practices. It appears in this case that this is perhaps not the focus for PHPMyAdmin.

Reflecting upon MarkBind and SE-EDU, I find that both CS3282 projects are heavily tested. For MarkBind, our scale is still relatively small with significant amount of resources available to ensure reliability. On the other hand, SE-EDU/AB4 is a role model for Software Engineering. It makes sense that these projects have reliable and extensive tests, and I see little reason to change.

LU YANG KENNETH

Suggestions for Markbind

I collated a list of Developer Experience Opportunities for MarkBind in this GitHub project.

MADDI AADYAA

Project: Gatsby

Gatsby is an open source framework based on React that helps developers build websites and applications faster.

How to Contribute: Information on contributing to issues, documentation, product website, and codebase.
RFC Process: Details on contributing substantial changes (using the requests for comments process).
Gatsby Style Guide: Guidelines for writing documentation and tutorials.

Contributions

What I Learnt

Define and Enforce a Workflow: Gatsby follows the standard forking workflow for bug fixes and small enhancements. More substantial changes follow the Requests for Comments process. Contributors must open a pull request that has a detailed document regarding their proposed change in a separate repository dedicated to RFCs. Having a separate repository provides an exclusive space for more focussed discussions on new features. I could see how this process is beneficial for a large open-source project like Gatsby as it helps them to control how new features are added to the project.
Have Dedicated Code Owners: Gatsby has 5 teams of maintainers that take ownership of different areas of the project. For example, pull requests need a review from the respective code owners. Managing a huge project like Gatsby can be quite difficult for maintainers as it has the codebase, product website, documentation, and other ecosystem features like themes and plugins. Having dedicated code owners makes it more convenient for the maintainers to handle issues and review pull requests in areas they are most experienced in.
Automate Repetitive Tasks: As it’s a popular product, Gatsby has a lot of activity in its issue tracker. Gatsby uses a bot to automate some repetitive tasks, like labelling issues based on their content and closing issues after inactivity. Additionally, they use a bot to update the project’s dependencies. Contributors also have have to follow specific pull request and branch naming guidelines which makes it easier for automated tasks to be run on them.
Motivate your Contributors: For an open-source project, motivating your contributors is extremely important. Gatsby has a comprehensive guide for contributors, which includes basic information on how to triage and label issues, submit pull requests, and writing good documentation. It also has an advanced guide that explains how Gatsby works behind the scenes. The quality of the contributing guide is what motivated me to work on this project, as it showed me that the project was serious about helping its contributors. Gatsby encourages contributions other than pull requests and commits. And there’s free swag for all contributors too!
Interact with your Community: Gatsby has their own Discord channel for providing faster support to those who need it. They also host free pair programming sessions where you can work on fixing an issue with a senior developer. Interacting with your project’s open-source community is important because it provides developers with a pool of resources, which gets things done faster.

Suggestions for MarkBind

RFC Process: Even though having a separate repository for proposing substantial code changes can be overkill, the RFC process could still be incorporated for adding new features to MarkBind.
Better Bug Reports: Require users to submit standalone MarkBind sites for reproducible test cases. Gatsby asks its users to create a new Gatsby site and add only those lines of code or plugins that cause a problem, publish the code, and link it in the bug report. This will be beneficial for MarkBind because the developers would not need to dig in through a lot of code to find the error, in addition to knowing the exact environment of the bug report.
Issue Categories: MarkBind already has issue templates, but we can take one step further and have different templates for different categories of issues like Gatsby does. For example, questions about using MarkBind and bug reports can have separate issue templates.
Comprehensive Contribution Guide: MarkBind will definitely benefit from a dedicated guide for new contributors on its product website.
Guides for Different Use Cases: Gatsby has standalone advanced tutorials for developing websites that have different use cases. MarkBind could have guides for developing a site that serves as a textbook, project documentation, or an eLearning resource. This will also showcase MarkBind's different features and versatility.

TAN ZHEN YONG

⚡ Serverless Framework

Website • GitHub

Project documents

Contributions

Observations

Clear starting point for new contributors

Serverless provides a clear starting point for new contributors in the form of their Contributing Guidelines, prominently linked to in their README.md. These guidelines cover the different ways to contribute (eg. PRs, feature requests, bug reports, documentation) as well as what to take note of before contributing, including testing and code style. Serverless also adopts a Contributor Code of Conduct, which sets out to ensure a positive environment for contributors.

By providing these guidelines for the many ways to contribute, as well as adopting a code of conduct, Serverless signals to potential new contributors that their efforts are welcome and are of value to the project. The variety of ways to contribute also widen the circle of potential contributors, inviting non-coders to contribute as well.

No clear documentation on internals

One potential issue for new contributors would be the lack of documentation regarding the internals of Serverless Framework, an issue even the maintainers themselves acknowledge. As such, I found it initally daunting to contribute, as the framework is a complex CLI application with 10 KLoC across over 1000 files. I eventually learnt through reading and debugging the code that the CLI was built for maximum extensibility, organised around the concept of different plugins that could affect any part of the framework while each plugin remained comprehensible on its own.

This meant that the project was not as hard to contribute to as I first thought, however clear documentation regarding the design of the framework would have been immensely useful in reducing the learning curve for new contributors and avoid intimidating them.

Specific and clear issue templates, aligned with error messages

Instead of having just a single issue template, Serverless has two: one for feature requests and one for bug reports. This allows Serverless to ask more specific questions related to each type of issue. For example, the bug report template asks for more specific diagnosis info such as version and operating system, which are not needed in a feature request.

In addition, the error messages generated by Serverless are directly helpful to filling out the information needed in a bug report:

  Get Support --------------------------------------------
     Docs:          docs.serverless.com
     Bugs:          github.com/serverless/serverless/issues
     Issues:        forum.serverless.com

  Your Environment Information ---------------------------
     OS:                     win32
     Node Version:           8.15.0
     Serverless Version:     1.39.1

This helps to improve the overall quality of bug reports, as users will not be confused as to what specific questions in the bug report mean, as well as making it clear where users can get help if they encounter problems.

Clear communication of PR workflow

When PRs are being reviewed, they are clearly tagged as being pr/in-review, pr/in-progress or pr/accepted. This clearly communicates to contributors where their PRs are in the pipeline, and if any maintainer has taken a look at their work. This helps to ensure that contributors see that the project is active and valuing contributors' time, encouraging further contributions.

In addition, the PR template has a detailed todo list at the end, detailing everything a contributor should check and do before submitting the PR. This ensures higher-quality PRs with the correct information and content right from the beginning as contributors know exactly what they need to do to have their PR considered. It also reduces workload on the maintainers as less time needs to be spent on asking for the correct information in a PR and more on the actual review process.

Fast and helpful responses from project maintainers

Issues are tagged and responded to quickly by project maintainers, with most issues being tagged with the appropriate labels in a day or so. In addition, the PRs that I have submitted usually gets a response after a day, which is impressive. The communications with project maintainers have also always been encouraging and positive. In one case, a project maintainer responded to my query on how testing should be implemented in a component by acknowledging that the test required was difficult, and wrote the tests himself.

The speed and positivity with which the maintainers respond to PRs and issues encourages new contributors, as they can see results and feedback quickly, as well as know that help would be provided by the maintainers and community if needed.

Suggestions for MarkBind

Explicitly document contribution guidelines

Like Serverless, MarkBind can also have a starting point for contributors in a Contributing document which cover the different ways to contribute as well as what to take note of before contributing, including testing and code style. MarkBind can also adopt a Code of Conduct. This gives new contributors immediate ways to start contributing, and signals to potential new contributors that their efforts are welcome and are of value to the project.

Create more detailed developer documentation

Like Serverless, MarkBind does not have detailed documentation on its internals. This may be intimidating to new contributors as they cannot clearly understand how MarkBind works before they start contributing. We should start creating more detailed developer documentation such that we reduce the learning curve for new contributors and avoid intimidating them.

Have more specific issue templates and align error messages

MarkBind can also have a specific issue template for feature requests, which does not need diagnostic information like a bug report. We can also provide help information within our error messages itself like Serverless which can then be directly filled into a bug report template. This can help users and contributors to provide higher-quality bug reports with the required infromation from the start.

Have a PR todo list

MarkBind can also have a detailed todo list at the end of its PR template, detailing everything a contributor should check and do before submitting the PR. This ensures higher-quality PRs with the correct information and content right from the beginning as contributors know exactly what they need to do to have their PR considered. It also reduces workload on the maintainers as less time needs to be spent on asking for the correct information in a PR and more on the actual review process.

PowerPointLabs

BRYAN LEW JU YU

External Project: Rocket.Chat iOS

Contributions:

Introduction

Rocket.Chat is a free, open-sourced team communication application that allows teams and individuals to communicate and collaborate using text chats, video and audio calls, and also supports screen sharing. It is an application supported on multiple platforms, including Windows, MacOS, Linux, Android and iOS. I chose to work on the iOS application for my external project as I was intrigued by the many features this application boasts and I also hoped to be able to learn a couple of new things along the way. Over the course of the semester, I was able to contribute improvements in 2 areas, and also add a new feature to the application.

Workflow

Rocket.Chat provides a brief contributor's guide for people who are interested in contributing to the project. It is a largely a pretty standard workflow, where contributors simply fork and clone the project, work on the changes on a new branch, then open a pull request when ready. They have naming rules for issues, PRs and branches which help keep things organised, and some special branch names also help to automatically skip CI builds.

Things I learned

1. Documentation is helpful and important

During the first few days of working on Rocket.Chat, I found myself lost in the thousands of lines of code, not knowing where to begin to look for the source of the bug. Usually when this is the case, we would go and look for any sort of documentation or developer guide to help us understand the code faster and to know more details, for example which classes are responsible for which features, etc. However, Rocket.Chat does not have any such documentation for its iOS application, but only has a small contirbutor's guide which does not have any details about the codebase itself.

Much of my time was actually spent trying to read and understand the code, rather than to think about and write out the solution for the problem I was trying to fix. I feel that this is a rather inefficient way of working, especially in a big project like Rocket.Chat, it would be better if there was some sort of documented guide for developers so that the time spent on trying to understand the codebase is minimised.

The saving grace was that the codebase was actually relatively neat and readable.

2. In an open-source project, an active and helpful community is important.

Continuing from my first point above, while documentation was lacking, the developer community in Rocket.Chat is strong and everyone is very helpful. From the maintainers to the senior contributors and the newcomers, it seemed like everyone was friendly and eager to help each other out, and everyone's queries are all promptly answered on both the PR thread, issue threads, and also a developer channel within the application itself! (it is a chat app that has a public server for all to join).

I was actually stuck on an issue for quite some time, initially relunctant to ask for help (because it was a pretty trivial problem!). But once I did reach out on the PR thread, I had a couple of replies within the next day or two, and was able to open a PR within the next week.

3. While it's good to be nice, code reviews must be taken seriously.

In all my contributions to Rocket.Chat, I find that the code reviews by the maintainers were all very thorough and detailed, and they always look to test and make sure the solution is working before it can be merged. They also require that the CI tests be passing before PRs are allowed to be merged. This is how they slowly build up a very clean and readable codebase, and it makes things easier for future developers as the process learning the codebase becomes less of a chore. I found myself slowly incorporating the practice of thorough and detailed code reviews into PowerPointLabs as well, as I realised the many benefits of not only merging working code, but also good quality code.

Comparisons to PowerPointLabs

PowerPointLabs can benefit from better community engagement and involvement, for both users and contributors. Possible ways are perhaps a public Slack channel where users and contributors are free to join and everyone can ask for any help and whoever is able to answer can help to solve the problem. Currently, we are handling user feedback and bug reports via email, which is not as personal and due to a one-to-one correspondence with the user, it might result in repeated work for us maintainers to give the same answer to the same question from different people. Having such a public space for direct messages can also make the exchange between users feel more personal and human.

In PowerPointLabs, while we do not have the best documentation, we do have some basic technical guides targeted at developers and contributors that can help with some of the technical issues that may arise during development in the project. In this instance, I think that Rocket.Chat can probably benefit from some sort of technical documentation to aid developers in writing code for the application, given the fact that is it actually a pretty large application.

SNG YU FENG CHESTER

External Project: Habitica

Habitica is a an open-source, online task management application. Instead of the usual way of task management, Habitica takes it a step further by gamifying it. It turns your life into a role-playing game where you complete real life tasks for experience and gold, which can gain you better equipments to pimp your character.

Pull Requests Merged

I fixed a bug where additional unusable options were displayed for certain items. PR #10965
I enabled usernames to be searchable in one of the pages and added test cases. PR #10980
I changed the login page to display more informative messages and added test cases. PR #11078

Workflow

The workflow of the project is documented here. It is vastly similar to PowerPointLabs, where contributors fork, create a new branch on their own repo, push changes to the branch and make a pull request. One difference is that there are no conventions to follow in Habitica in the naming of the branches and pull requests.

Takeaways from the External Project

Habitica has been a pleasure to contribute to because of various reasons.

The main reason being their documentation is clear and easy to read. Habitica has its own wiki page that contains a lot of information about the application itself. Their setting up guide and instructions for contributors are also on the same wiki, giving a native feel to their documentation.

Fun Fact: Contributors on Habitica are not called "contributors", they are called Blacksmiths.

Habitica shows Blacksmiths what they can contribute to on their Guidance For Blacksmiths.

On the same page, you can find that Habitica also introduces the workflow of the project. Some FAQs like where to add images, where to add translatable strings are on the same page. Also, even though MongoDB might be widely used, Habitica also has a small section to teach Blacksmiths how to modify the database so that they are able to test their changes.

For someone like me who only knew MongoDB is a great database system and not know how to use it, their instructions really helped me in my contributing process.

Blacksmiths are awarded Contributor Tiers

Habitica shows their appreciation for Blacksmiths by awarding Contributor Tiers once the pull request gets merged. For example, you can see in my first pull request, I was awarded the first contributor tier. In game, this achievement comes as a badge viewable in your own profile. Contributing more or longer pull requests will increase the contributor tier accordingly. Here in my third pull request, I was award the second tier.

You can see why users of Habitica will be willing to contribute to Habitica: because Habitica gamifies the contributing as well! If you are contributing artwork or a sound piece, you will be awarded a different contributor title as well.

Help is always available for Blacksmiths

Habitica has a Guild set up for Aspiring Blacksmiths. Blacksmiths that have difficulty in solving the issue can post their questions on the chat where other blacksmiths or administrators will readily help and give suggestions.

Practices/Tools that can be adopted by PowerPointLabs

Call/Recognition for Contributors

There are a lot of contributors for Habitica and I believe most of them are using the Habitica application themselves (since you are able to get achievements by contributing). One possible way we can more contributors for PowerPointLabs is to advertise that help is welcomed on our website.

In addition to that, we can have some sort of recognition for contributors. For example, having a list of names of past contributors on the github page. For example in NUSMods, there is a list of contributors and their github profile pictures on their first page.

Continuous Integration

Habitica has a lot of tests (runs for 18mins in asynchronously, total time 45mins). This is the Travis build on my first PR.

Continuous integration will help to keep the application away from regression. Currently, there is no easy way for PowerPointLabs to implement Continuous Integration (due to need of needing PowerPoint installed).

As a result, extensive testing needs to be done on pull requests by reviewers manually so that the new changes will work on PowerPoint 2010, 2013 and 2016. At the same time, this is not efficient as it requires the reviewer to manually run the functional and unit tests.

Documentation

In comparison to the documentation in Habitica, the documentation in PowerPointLabs seems to fall short in being organised. For example, the contributing guide contains information about submitting an issue to the release strategy of the project.

Althought it is very informative, perhaps we can keep the contributing guide focused and also contain relevant contributing information from the newcomer guide.

Also, in Habitica, the documents links to each other logically. Once an interested contributor opens up the Guidance for Blacksmiths, they are provided links to the Setting Up Guide and Contributing Guide.

We can also try to make PowerPointLabs guides link to each other logically also. For example, I had problems setting up the PowerPointLabs development environent on Visual Studio. However, the solution can only be found in Common Traps, instead of the setting up guide.

YU PEI, HENRY

External project: Git for Visual Studio

link

Contributions to external project:

Online documents of project's workflow

Things learnt from project

Error dialogs in the application are extremely helpful in assisting new contributors in finding code related to bugs, in a project of such a scale (estimate over 30k LoC, with many modules).
Finding more good first issues might be a good way to encourage new contributors to help out. Currently there is only 1 good first issue and is stale as someone asked to do the issue, but his rather old PR did not get closed after a rather long period. link to PR. This made me a little reluctant to start as other issues require some amount of understanding of a significant part of the project. It is observed that the external project does not receive new contributors often.
Adding a label to an issue to describe the scope of the bug can be very helpful for new contributors. I had to rely solely on error dialogs, debuggers and some logging to find the cause of a bug.
PRs that lacked description of what it fixes, how it is fixed and what tests are written are often rejected. This is important as both the contributor and the developr should be confident of the changes being introduced.
The project uses a ReadyForReview label for developers.
The project seems to be open to adhoc documentation fixes from public contributors. Example
The project uses milestone deadlines to have certain PRs merged/reviewed/completed. However, the pattern is not clear.
The project merges PRs that fail CI tests by their internal memebers, probably because CI tools report false positives at times.
The project uses projects to manage issues pertaining to different aspects of project management, such as maintaining/building a feature area, or fixing bugs and polishing the code.
The project uses development sprints to push new enhancements. The project also utilises a bot to push new releases.

Practices/tools of the external project that may be adoptable by NUS-OSS

Use milestone deadlines for PRs/issues.
Use projects to plan for longer term development.
Use a bot to publish releases, and have development sprints (but the team is a little small for benefits).

[Optional] Suggested areas of improvement for the external project

RepoSense

CHELSEY ONG HEE

Project: JabRef

JabRef is a citation and reference management tool that helps you collect and organize your research materials.

Contributions made:

Add a variable to track the change in preview style #4587 (Issue, PR)
Enable default cursor for new entry #4604
Fix preview style configuration #4613
Fix: bibkey generated does not handle diacritics #4713

Workflow

For each pull request made, it is required to fill in a checklist. The checklist looks for 6 points - Tests are created, manual testing is done, screenshots added if UI is to change, good git commit messages are written, documentation is updated, and the change is properly logged in the file.

I feel that this is a very good practice to remind developers to fulfil a certain criteria before requesting for reviews from the developers. This is especially useful for newcomers who are not familiar with the project's contributing workflow. In a way, this can also speed up the reviewing process as reviewers do not have to check for things that are already on the checklist so they can focus on ensuring good code is written instead. However, in JabRef, this checklist is commonly ignored and only certain bulletpoints are looked out for. I believe they can update this checklist to make it more relevant to both new and existing contributors. For example, the documentation status seems redundant as it is often expected of the PR author to update documentation when the code changes.

Issues are also organized into 3 categories, namely JabRef UI Usability Improvements, Bugs, and JavaFX UI Rework. Every category has a set of issues with differing priorities. Whenever an issue is closed, an automated bot will move it into the "closed" group. This is an interesting way of tracking all issues and their assigned priority levels at a glance. As RepoSense is solely relying on the issue tracker which acts like a "noticeboard" for all the issues posted, it can become hard to handle when there are more bug reports or feature requests with the increased number of users in future. By partitioning issues into relevant categories, developers have a more efficient way of looking at a smaller pool of issues that deserve greater attention.

Tools used

The tools used by JabRef are Codacy, Travis CI and DEP. CI does a good job in ensuring that the new code passes all tests, including integration and database tests. Codacy is mainly used to check for checkstyle issues. DEP is a bot that checks for PRs which rely on other PRs/issues to be merged before they can be continued. It becomes useful when many people are working on similar areas in the project at the same time. Developers become more aware that they are working in a group and close collaboration is often needed to ensure good code quality. This may be applicable to RepoSense's frontend development where many conflicts occur when new PRs are merged and this can slow down the whole contributing process and bring in unnecessary bugs in the code.

Documentation

There is a Wiki page on JabRef that provides information about how to use JabRef and ways of contributing and developing code, such as best code practices used by JabRef specifically. As such, new code written can fit into JabRef's context easily. This is similar to the User and Developer Guide already used in RepoSense. In future when more tools are integrated into RepoSense, notes on how tools RepoSense use can contribute to a better contribution workflow, may be written in the Developer Guide to teach new developers how to use these tools more effectively. A FAQ section can also be written in the Wiki page, especially common questions that are often asked by students who are using RepoSense. A benefit of using a wiki page instead of a markdown file for documentation, is the ease of browsing through the different sections, without having to scroll back to the top of the page to find the table of contents, as this can be quite frustrating for new users who are struggling to use RepoSense.

I had encountered some difficulties trying to set up the project, because it uses JDK8 and some deprecated libraries that cannot be resolved by IntelliJ. Since new JDK libraries are mostly used in development these days, using older libraries can slow down the setting up process and delay the time used to write actual code. Git submodules have to be installed to use citation styles when viewing reference entries, but I feel that it is actually quite neat to be able to install additional libraries through Git without having to download another set of files during the development stage. Nevertheless, the guidelines provided by JabRef are very easy to follow along. Additional help from the JabRef community is also available through the gitter channel. If one prefers learning by following instructions, a video tutorial is also available.

GILBERT EMERSON

External Project: Electron

Links:
Electron Development Documentations

I appreciate their very structured and ordered contribution guideline, as Electron is a very big open source software. Not only that, Electron has quite cool contribution flow, going all the way from creating issue to getting your PR merged. What I observed from their process as well as how it might be applied to RepoSense are as follow:

Structured Issue message
This is to ensure that the issue can be triaged faster and more efficient. This goes all the way from differentiating bug issue and feature request issue, and then there is issue template that developer can follow including a checklist for developer whether they have checked for existing issue, etc.
RepoSense perhaps can follow this procedure to improve issue management.
Semantic commit message
Electron follows Semantic Commit Message to streamline release process. RepoSense can implement this alternative commit message guideline if it does not want to follow the rigorous SE-EDU as for now RepoSense does not really have any commit message guideline.
Semantic Prefix for PR Title
This is to ensure that the PRs are nicely organized. This enforcement is mandatory in Electron. RepoSense can learn to implement this better as PR title in RepoSense is still quite haphazard.
Semantic PR message
Electron's semantic PR message is not only for stylistic purpose, but it is linked to their bot automation. For example, you can include release note by adding notes:, which will be detected by Electron's release note bot and then it will process accordingly. While this may be an overkill feature, RepoSense can follow this structure if it will use automations in the build and release process in the future. The automations involving bot will be expanded below.
Welcome Bot
Electron has a bot that welcomes new contributor. Upon creating their first PR and merging it, they will be greeted with the bot. The bot will remind the user with all the contribution guidelines so the user can follow in closely if they have failed to read it beforehand. RepoSense can benefit from this when RepoSense is larger to remind new contributor what to do when they have submitted their PR. Also, with the welcome bot we can easily differentiate who is a new developer to RepoSense and who is not.
Clerk Release Note Bot
The bot checks for notes: prefix in PR message and update the release note accordingly. This is according to the idea that commit -m is for maintainers while notes: is for users. Although this bot is proprietarily developed by Electron team, RepoSense might be able to find third party alternative if RepoSense want to implement this feature in the release cycle.
Automatic backporting
As Electron has multiple version releases which are hosted in separate branch, a change made to latest release might need to be propagated to the previous release, essentially backporting it. This is accomplished also by automatic bot that create auto PR to previous version branch by tagging the PR with specific tag. While RepoSense currently does not have multiple version release, this idea might be beneficial for RepoSense to explore in the future.

I also appreciate that despite being a large open source software, their most active developers are very active, responsive, and helpful in providing assistance and reviewing my code. While this is something that we may already know intuitively, perhaps from this we can be reminded again to be helpful and responsive to foster a good Open Source community.

External Project: NUSMods R

Links:
Contribution Guide

NUSMods has its own development chat channel via Telegram. Personally I think Telegram is not the best medium as it is more of a group chat where it is very easy for a discussion to go out of control and people that is not involved will not get what is actually being discussed. I found that NUSMods Telegram group is more of a group chat for the core developers and the contributors are mostly there just watching them discussing. It will be on rarer opportunity such as feature request or asking for guide from the core developers will the contributors be active in the group. I found that Slack which is already being employed by RepoSense to be more appropriate, despite RepoSense slack is not as lively as NUSMods group.

Nevertheless I appreciate NUSMods core developers openness and willingness to help. They are quick to respond and give advices, and the fact that they invite all contributors to the group and we can see all the chats there signifies those. They are also quick to reply and do not hesitate to help, signifies by my discussion with one of the core developers when I found some problem in my PR.

External Project: nsfwjs

Links:
All Contributor Guideline (used by nsfwjs)

One noteworthy observation from this project is that they follow All Contributor Guideline (link above). They acknowledge any contributors contributing in any aspects such as UI, documentation, etc. I find this to be very encouraging, especially for new open source developers and this can motivate and encourage them. I find that this will create a very warm and hospitable open source community. Perhaps RepoSense can follow this guideline or modify it to fit its own purpose to enhance current contribution acknowledgement.

ONG SHU PENG

The particular project that I picked was part of a collection of firefox extensions. As such, they use many general libraries for rendering tooltips, popups, and interacting with the browser content.

These libraries are "imported" using the git submodule and any updates to the libraries can be easily updated through git as well. Using git submodules to manage libraries was new to me, and this was a concept that would be relevant for bigger projects with many moving parts.

However, this may not be so relevent for RepoSense. Even though the frontend report interface may be thought to be a separate component from the java backend which generates the report, they are too tightly related, the frontend having strong dependency with the format of the generated reports.

Another observation was the use of the .editorconfig file. The collection of firefox extensions is a rather large project with many different contributors. To help with the setting up of the development environment, this config file will handle code style such as indentation and trailing spaces.

For projects with many different contributors this can be useful to automatically handle the different types of indentation styles. Since most editors respect the .editorconfig file, little has to be done to manage the file.

For RepoSense, this is something we could definitely do, using a .editorconfig to handle different kinds of code style. This is especially important for CLI based text editors such as vim where such options cannot be conviniently changed.

However, to tackle this issue, code style checkers such as eslint and checkstyle is used as part of the CI process to enforce a certain code style. The .editorconfig file can still come in useful for files where the style checkers miss (e.g. css files). With this configuration file, there would be less cases of early PRs having offending whitespaces changes.

Another useful thing to note is that most web based ide as offered by major code repository hosting platforms like github, gitlab and bitbucket do offer support for this config file. Therefore, this will make it more convenient for developers to work on their code, using these web ides.

WANG CHAO

Project: CheckStyle

Checkstyle is a tool for checking Java source code for adherence to a Code Standard or set of validation rules.

Links

The link of the workflow of contributing to CheckStyle is here

Contributions made

Workflow

The basic workflow is like this:

Submit an issue and wait to be approved or choose an approved issue from the issue list.
Work on the issue and squash the changes to one commit.
Raise a PR and wait to be reviewed.
Edit your PR until being approved by all maintainers.

The workflow of CheckStyle do not have a big difference with RepoSense and SE-EDU.

Impressive aspects

There are two impressive aspects when I contributes to CheckStyle. One is CI Test, another is Diff Report.

For the CI Test, CheckStyle has 17 checks to pass in order to proceeded with PR. The tests covers a variety of aspects. For example, it ensures that the project is able to run on all JDK version and all Platforms. Also, it requires the code to have 100% coverage. 100% is even not enough for the tests. CheckStyle also have a test named pitest, which is a kind of mutation test. It is basically modifying the test code to look for tests failure. It will find out the lines that are able to be modified without tests failure, which indicates either the test case can be improved or the main code can be improved.

For Diff Report, basically, it ask all the changes related to main code that may cause a regression to generate a diff report, which compares the result of analysis generated for a large number of public repos before the change and after the change. This process is to ensure that no regression happens after the change. This tool is written by the developer of checkstyle and it plays an import role in the workflow of CheckStyle.

Suggestions to RepoSense

For now, RepoSense do not have a coverage test yet, which may because the test coverage is not satisfying at the early stage of RepoSense. Now, we already have a high code coverage, so the previous concern is not true anymore. Also, having a coverage test allows us to improve our testing with higher revenue and lower costs. So, maybe RepoSense should integrate coverage test now.

We already have a Netlify preview for some Repos which plays a similar row with diff report. However, it is not same. For now, we basically analyze the preview manually to see if regression happens. Maybe we can develop a tool that are able to analyze the difference of the two report generated so we can have a better insight of potential regressions.

Suggestions to SE-EDU

Currently, AB4 has coverage test. However, it do not have mutation test. As a project that teaches students about SE related knowledge, maybe we can integrate mutation test in our code because it is reasonable to let the students know that there is another kind of test to test code quality.

Because AB4 is not analysis based application, so a Diff Report is not suitable for AB4.

Suggestions to CheckStyle

Firstly, the developer guide of CheckStyle does not give an overall structure of CheckStyle and how each component interacts with others. Since CheckStyle has a huge code base, it is quite hard for a new comer to contribute to Checkstyle. The new comer have to take a lot of time to be familiar with checkstyle, which is quite hard and requires higher skills for the contributor. This may block the new comer away from being an actual contributor.

Secondly, the commit message of CheckStyle only contains the information of the issue number related to this commit. So, the developer cannot get any information of this commit from the message directly. It is harder for the developers to locate and analyze the bug. Things get even worse if there is a long discussion in the issue/PR page in github, it is really difficult to find the true important information. Maybe CheckStyle should add some relevant important information in the commit message so the developers are able to get the required information more easily.

TEAMMATES

AMRUT PRABHU

Project: NUSMods

NUSMods is an unofficial module planning platform for National University of Singapore (NUS), and is practically used by all NUS students. Currently, it offers a semester timetable planner, module information bank, a course module planner, and a venue locator and availability checker.

My Contributions:

Pull Requests:
- Highlight search period in Venues page
- Clean up cyclic references
Reported Issues:
- Highlighted search period doesn't match with search options in Venues page
- Footer overlaps with side navbar

NUSMods Project Guide

Here is an overview of the parts of the NUSMods project guide.

The project README links to the 5 subprojects that make up the NUSMods repository. Each of these subprojects have their own README (with varying levels of completeness) that highlights what the subproject is about, the processes involved, and how to get started with contributing to it.
The document also provides links to the NUSMods communication channels, the main one being Telegram. The community is active on Telegram and have open discussions about the project direction and design choices, apart from providing updates about new features.
The Contributing section has the typical elements: Code of Conduct, Setting up Guide, Development Workflow. The details provided are comprehensive, yet to-the-point.
- The project is easy to setup as subproject-specific details are provided and no project configuration or external tools (apart from standard ones like Node and Yarn) are required.
- In order to fix an issue, it is recommended to state your interest in taking up the issue. This is to prevent other contributors from working on the same issue. The documentation also specifically states that if you don't follow up on it for more than two weeks, others can take up the issue.

Comparison with TEAMMATES process

This section provides more specific details about the NUSMods process and practices, by comparing it with the one used by TEAMMATES.

Differences:

Open Communication Channels: NUSMods uses Telegram and the GitHub issue tracker as their primary communication channels. Uncertain features are discussed in depth in the corresponding GitHub issue so that potential contributors have an idea of how to go about resolving the issue. The Telegram group is used for requesting for help with small problems, informing members about minor updates, and some review requests.
Deploys Previews: Netlify is part of the CI checks in pull requests (PRs) to NUSMods. Hence, each PR comes with a deployed website preview with the changes made. This allows reviewers and contributors to see the bug fix or feature in action, without needing to locally deploy the changes made in the PR.
Uses Absolute Import Paths: NUSMods uses Webpack to resolve most TypeScript import paths to absolute path, instead of relative paths like the ones in TEAMMATES.
Automates Dependency Management: NUSMods uses the Renovate bot to automate management of its npm package dependencies. It creates new PRs when a new version of a project dependency is released. TEAMMATES doesn't have any such process. In fact, it is done manually and only on a need to basis- when a released version has a new feature or introduces several big changes, for example.
Few Active Contributors: NUSMods only a handful number of active contributors since it has a smaller target audience, i.e., NUS students. In contrast, TEAMMATES regularly gets contributors who generally fix a couple of issues. In addition, there are dedicated groups of contributors who work on subprojects, owing to CS3282.
Simpler Labelling Process: As a result of the previous point, NUSMods does not extensively use labels for PRs (like s.toReview, s.finalReview) unlike TEAMMATES which has an extensive labelling system. Since NUSMods only have a couple of project maintainers, an extensive labelling system may be overkill too.

Similarities:

Uses Issue Templates: Like TEAMMATES, NUSMods has GitHub issue templates for reporting bugs and requesting features. This helps standardise issue formats and also guides the authors in terms of what information needs to be provided to make the issue complete. The NUSMods templates do feel better since they have pseudo examples that can be modified, and they specify exactly what information is to be provided in the issue description, without the template feeling too cluttered.
Uses Forking Workflow: Both projects use the forking workflow with regards to making contributions. Though maintainers have push access to the repository, they do not push directly to the master branch. Their contributions are still subjected to the same review process as others.

Suggestions for TEAMMATES

After my experience contributing to the NUSMods project, here are some takeaways and suggestions that are applicable to TEAMMATES:

Communication Channels: Though TEAMMATES does use a communication channel outside of GitHub, it is primarily used by current CS3282 students. Even then, the subproject-specific channels are made private. This restricts other interested contributors from being informed about what's happening and seeing the reasoning behind certain decisions (which can be a learning opportunity). For example, this issue does not provide any useful information (maybe it's supposed to be that way, but this point still holds).

TEAMMATES should invite potential contributors to join the Slack workspace, unless there are some external factors behind the current decision to make it selective (like requiring a paid Slack plan in case the number of messages increases by a large amount; this is unlikely, but something to consider).
Managing Dependencies: TEAMMATES can automate dependency management by using tools like Renovate bot. It can update the npm and Java dependencies by making PRs to the main repo. A potential issue here would be the creation of too many PRs, which would clutter the GitHub PR tracker.
Documentation: Though TEAMMATES has good documentation as compared to many other open source projects, it can use a couple of minor updates:
- File structure: Explain what files are in which directory in the contributors orientation guide, similar to NUSMods' subprojects. This will prove useful to newcomers, especially now, since we are in the process of migration. A new contributor faced a similar issue which could have been prevented by stating that the frontend of the project has been moved to the src/web folder and the legacy files are meant to be deprecated.
- Inactive contributors: Indicate the amount of time that has to pass before an issue can be reassigned in case the previous assignee does not follow up (doesn't respond or did not make a PR).
- Code documentation: It is decent, but can still be improved in terms of the covered classes and functions, as well as the level of detail (especially if there is something important that needs to be noted). This is not critical, and will require a considerable amount of effort too.
Deploy Previews: TEAMMATES can start adding deployment of previews to its CI pipeline. This will allow reviewers to extensively manually test bug fixes and features before approving the corresponding PR. We will look into whether this is feasible, considering the fact that the frontend does not work without the backend server anymore.
Absolute Imports: In terms of code style, TEAMMATES can use absolute paths for TypeScript since it provides more information and better navigation, compared to relative paths. Since using Webpack (like NUSMods) may be too heavy, alternatives like modifying the tsconfig can be considered instead.

CHATTORAJ AYUSH

Project: FOSSASIA's chat.susi.ai

My Contributions: Pull Requests:

[#2052] (https://github.com/fossasia/chat.susi.ai/pull/2052)
[#2068] (https://github.com/fossasia/chat.susi.ai/pull/2068)

Issues:

[#2067] (https://github.com/fossasia/chat.susi.ai/issues/2067)
[#2051] (https://github.com/fossasia/chat.susi.ai/issues/2051)

Documentation: Contributor Guide: included as part of the README

Observations: FOSSASIA's SUSI.AI is an artificial intelligence system, combining pattern matching, internet data, data flow, and inference engine principles. Since chat.susi.ai has consistently been a Google Summer of Code project, and FOSSASIA has a reputation for being open towards first-time contributors, I thought it'll be a good experience. I also wanted to diversify and try new things - since I had had experience with VueJS, and was doing Angular in my internal project, I thought the ReactJS based chat.susi.ai would be the best option for me.

Frameworks:

The chat.susi.ai is a front-end developed for web access of SUSI, and is written in ReactJS. Right out of the gate, I noted the difference in the choice of front-end frameworks between my external and internal project. Since I primarily worked on the front-end for both projects, I noted that ReactJS is significantly easier and has a much gentler curve as compared to Angular. Since TEAMMATES aims to be a student-driven project, I have fairly mixed feelings about our decision to use Angular.

Contributing:

While their contributor guide is very barebones compared to TEAMMATES's extensive guide, their project is actually fairly easy to set-up, and has significantly fewer rules. Their coding style is actually fairly inconsistent, unlike TEAMMATES, which has a very stringent lint. I wouldn't categorise either as good or bad, since both work just fine.

chat.susi.ai also is also less welcoming to first-timers, with no issues being flagged as first timer issues. Instead, they have a very unusual system where most contributors point out missing features themselves, and state in the issue description that they are working on the missing features (in fact, the default message for opening an issue already includes the question 'Do you want to work on it?'). I definitely prefer TEAMMATES's approach, where relevant issues that are currently the focus of the team are flagged out for first timers. They also take significantly longer to respond to PRs and queries on average.

They also have multiple reviewers per Pull Request, and it is very disorienting to try to please all competing reviews on your Pull Requests. This is stark contrast to TEAMMATES, where the Project Lead strictly told us that no more than 2 contributors should review any PR, unless there is a very glaring error that has to be pointed out. This ensures that the person making the PR is not trying to juggle multiple competing suggestions at once.

However, as a project with a more established front-end, they do have some very nice features that would be great for TEAMMATES.

Particularly mention-worthy would be surge.sh, which is a website that allows you to quickly deploy your front-end on a URL for free. All PRs made to chat.susi.ai require you to mention the surge.sh link the project is deployed to, and the reviewers will look through the actual front-end. This, in my opinion, is better than the snapshot tests we are currently running on auto-update mode to test the rendered final product, as it is significantly easier to just look at the web page, instead of trawling through thousands of lines of HTML. I think TEAMMATES will greatly benefit by combining the use of surge.sh (or similar platforms like netlify) and snapshot tests, as we can hasten the process of looking through the rendered snapshot for the 'ideal' case, and all subsequent checks can be done against an 'ideal' snapshot quickly (snapshot tests will still be needed to test all 'other' cases, but since they are less likely than the ideal scenario, it should still reduce the review workload significantly). I understand that the logistics of this will be fairly challenging, but we can explore options such as making stubs for all the API endpoints, among other things, especially given that our front-end is in such a nascent stage.

Takeaways

While I certainly learned a lot about ReactJS and CSS for the purposes of making this contribution, I learned much more about how to be better reviewer, as I understood the shortcomings of a relatively poorer reviewing system. I learned that it is crucial to be enthusiastic and supportive towards contributors, as it encourages them to continue not only towards this specific project, but also Open-Source projects in general, and that we should definitely ensure that our committers have a bit more guidance when they first come onboard and start managing the project, as the reviewing process can really shape the experience of contributors.

JEREMY CHOO WUN KA

External Project: Netrunner

About the project.

Netrunner (hosted on jinteki.net) is the digital platform to play the card game Android: Netrunner, a game set in a dystopian, sci-fi future where MNCs control the world and a group of hackers attempt to hack into those servers for their own personal reasons.

Project Information

There is a slack group for developers to ask for help or discuss improvements what improvements they want to add. Invitation is gained by submitting a PR. There is also a setup guide as well as some documentation located over at /wiki page. It has decent documentation and videos on how someone went through bug fixing. The workflow is like most other projects – post in an issue if you want to work on it, then submit a PR when you’re ready. It goes through a review process and gets merged after if it passes.

Documents

Most of the documentation and information about the project, however, can be found on the wiki page.

My Contributions

Learning points

Clojure

My main learning points from contributing to the project is learning how to use Clojure, a lisp-like language. Since Lisp and its variants are very different from the programming languages that I have learnt, some tasks in which I thought were easy to do has ended up taking days just to figure out what had to be done. However, through contributing to this project I’ve come to appreciate the use of Clojure in the macro level. While working on the project, it seemed like I was building the game in a language that was built to build the game, similar to how game companies build their own custom game engines for their games, this felt as if I was working on a game engine built to create Netrunner – yet that was obviously impossible, since the project was built on Clojure, not a game engine. Yet, due to the way the language used macros and virtual functions for metaprogramming, it felt like I was not working in Clojure, but a game engine built for Netrunner.

Fixing problems in an unfamiliar codebase

Many of the issues that I attempted to fix was resolved by thinking of a similar card that does a similar function, and then trying to adapt that function over to the actual card. The simplest example is when I tried to implement Cold Site Server, where I heavily referred to Ruhr Valley for implementation details. Unfortunately, that implementation failed because Ruhr valley was bugged, which led to a wrong implementation for Cold Site Server.
It turns out other people used this method too to fix bugs and add features:

Feeling Involved

Another important thing I learnt while working on the project was the importance of communication between all the members of the development team. The slack channel set up for Netrunner is the main source of communication for all developers, and thus everything goes into the channel, be it thoughts on future development/features, further insight into code snippets or questions on how to do X. Since everything is communicated there, it acts as a big source of motivation to work on the project as well, since you read about others implementing feature X and Y or fixing some bug, which really motivates me to do the same. Furthermore, discussions on what is planned helps developers to be involved in the future direction of the project. I feel that this is hugely important to help encourage new contributors to stay and continue with the project, otherwise they would feel like they are just being used to implement new features or fix bugs that no one else wants to do and thus was assigned to them.

Suggestions for internal project

Involvement

I feel that keeping people involved through discussions on the future of the project, or what is going on within the development team is a very important practice that teammates can adopt. This is particularly true especially since teammates (and other NUS-OSS project) gets a yearly infusion of people to work on the project, which no other open source project has. Due to this, teammates have grown differently from other projects. Since most contributors live in Singapore, many discussions on teammates happen offline, be it requests for help or new features. Sometimes, they occur in private slack channels. Despite Teammates's OSS policy (wherein it is said they they'd prefer to discuss everything openly, using the issue tracker as a forum) there are many things that don't go on there. Since they don't happen online, others can't find them if they're encountering the same issue. Additionally, because other developers don’t get to listen in on what the senior developers are discussing, it is harder for them to see the bigger picture. Losing this main channel in which all developers are included loses a lot of the motivation that people get when working on the project. You only get to see glimpses into a small part of the project. This difference in how teammates is organized, unlike other OSS, is what I think Teammates’s biggest problem is, and why it has such trouble in retaining people to work on the project.

Documentation consolidation

Unlike teammates, Netrunner has all its documentation in a single location, located under the wiki page. This provides several advantages:

Documentation is all consolidated in one place, making it easier to find what you want - when I was looking for documentation in the project, I simply had to go to the wiki page and check the table of contents for what I need. However, with teammates, documentation is scattered all over the readme file, some embedded within several layers of links. I think that teammates would derive a large benefit from having all its documentation easily found and consolidated in one place rather than having developers search for it (sometimes with Google!)
Ease of editing. Through the wiki pages, Netrunner's documentation can be easily editable, without the need to go through a PR and make changes. For example, when I found an event hook that was not listed in the wiki, I was able to simply click Edit on the wiki page and add the event hook myself. This made it easy and seamless to update the documentation of the project.

JIANG CHUNHUI

Project:

Kentico Cloud Swift SDK

Documentation:

Contributions:

Observation:

As shown in the above documentation link, they also use the feature branch workflow, which is similar as TEAMMATE's.
The KenticoCloud iOS SDK developed by Kentico CMS is a Swift library used for retrieving web content. Since the SDK is target to developers rather than general users, the documentation is quite detailed in terms of both developer guide and inline comment. As shown in this link, they require documentation in every public member in order to make it clear for other developers.

What I have learnt

Write meaningful commit message and organize commit messages well. I found it important because as I used to have messy commit messages, sometimes I even confused myself when I wanted to track some files. Organizing commit message is quite a valuable skill that I learnt from contributing to open source project. TEAMMATE also emphesis organzing commit messages.
Read documentation of dependencies, and be careful to block main thread. In this PR, my first approach blocked the main thread, which was pointed by the maintainer. He also told me to read some documentation of dependency modules, and finally I implemented better functionality. Sometimes the dependencies have provided API that can solve the issue. I should explore them before implementating the feature from scratch.
Follow some contribution etiquette. This is written in thier contribution guide. I used to try to refactor the code for my better understanding before fixing the issue. However, I realize that applying this will cost extra effort for maintainer to review my refactoring, and is not a good practice to contribute to open source project. This link about etiquette can also be put on TEAMMATE since it will be contribute to large number of developers.

Tools

Auto-generating documentation: jazzy
Testing: Quick/Nimble

However, after exploration, these framework are typically designed for Swift/Objecive-C. Therefore, it is not applicable to NUS-OSS project currently. However, there are similar tools that support for other languages, such as Javadoc which can be used for TEAMMATE.

Suggestions to TEAMMATE

TEAMMATE can pay more attention to documentation, especially the developer guide. As an API developer, I often find it costing a lot of time to understand how does the API work, and try to consolidate it. Since TEAMMATE is intended to be contributed by a large number of developers, it is important to help them understand the codebase quickly. Therefore, I believe the developer guide on API layer is necessary for both backend developers to improve the API and frontend developers to use API. It will be better if the developer guide on storage lay can also be provided.

LI PENGCHENG

Project: Oppia

Contributions

Link to getting started with Oppia

Observations about the project

About the Project - Oppia is an online learning tool that enables anyone to easily create and share interactive activities (called explorations). These activities simulate a one-on-one conversation with a tutor, making it possible for students to learn by doing while getting feedback.

I chose this project as I believe a tool to help with learning is very important. Also, Oppia uses a framework which I am already comfortable with. Oppia is built with Google App Engine and it uses Python as the backend and AngularJS as the frontend framework. This is fairly similar to Teammates which makes a good platform to apply the things I learnt about Angular and also understand how to write Python backend code.

Key takeaways:

While I learned about the general framework of using AngularJS and Python, I also learned about integrating testing tools offered by AngularJS such as Jasmine and Karma.

1. High Testable Code - I recognize the importance of having extensive tests ranging from backend, frontend to E2E test. It is important to cover all the test cases in order to ensure that the application does not fail in any way.

2. Interaction with fellow developers - Oppia uses Glitter to welcome, communicate and disseminate any important announcements to the development of the application. I feel that it is a great way to understand how senior developers think and challenges they faced.

Improvements for Oppia

1. Since it is a fairly large codebase, it will be good if the project can support or promote an IDE to help with development, similar to what TEAMMATES has done. Currently you can only run the virtual environment server in terminal.

2. It is good that there is a documentation template for each component in order to standardize. However, only the high level documentation is completed and it relies strongly on contributers to help with the documentation of smaller components which has no progress for months. Hence, basic documentation of each component could be completed to help contributors in the process.

3. There is no default data in local server which helps developers to understand the web application better. This practice is followed in TEAMMATES and it will be a good addition to the Oppia project.

Suggestions for TEAMMATES

1. TEAMMATES could consider incorporating a channel and survey system in onboarding new developers. Oppia requires new developers to fill up a survey so that its team can allocate the right project for each developer depending on the strength, availability and goal of the developer.

2. Another area that TEAMMATES can work on is to allocate mini projects to contributors who have made a certain number of contributions. Oppia invites developers to be collaborators after 2 merged PRs to help out with more in-depth projects and dicussions.

3. In terms of testing, Oppia is very driven by codecov report and aims to get 100% coverage for all tests so they have open PRs for anyone to work on any tests to help to improve the coverage. Since TEAMMATES also aim to achieve high coverage, there can be issues opened for anyone to work on improving tests cases as well.

4. Oppia made users to automatically check all styling before a successful push can be made to the repository. I think this is applicable to TEAMMATES to help to reduce the check style fails.

MONIKA MANUELA HENGKI

Project: Mozilla Firefox

My contributions:

Documentation:

Tools:

VCS: Mercurial
Bugtracker: Bugzilla
CLI tool to submit patches: moz-phab
Patch review: Phabricator

Observations

Mozilla Firefox is is a free and open-source web browser developed by The Mozilla Foundation and its subsidiary, Mozilla Corporation. I chose to contribute to Firefox because I wanted to be involved in one of the largest open source projects. Because of this scale, I can find many ways where I can contribute based on the language I am comfortable in (Javascript and Java).

Key takeaways

Throughout the process, I have learnt a few lessons not only as a contributor, but also as a maintainer of an open source project.

#1 It is important to have an active community of developers who are ready to help.

As a new contributor to Mozilla, the biggest obstacle I faced was getting used to the tools used in the workflow. I am used to git for version control (VCS), and Github as the bugtracker, PR tracker, and repository storage. However, Mozilla uses mercurial for VCS, Bugzilla to track bugs, moz-phab to submit patches, and Phabricator to review patches. Not only did setting up the project take some time, but the difference in tools used also created extra hurdles to me. Although the tools are quite well documented, the amount of documentations I had to read were overwhelming especially to new contributors.

Even when I faced these challenges, help was readily available. There is an IRC channel dedicated to help new contributors get started. I have asked some mercurial-related questions and within 5 minutes, my questions were answered by an experienced developer from the community. Furthermore, many of the bugs were mentored. I was fortunate enough to work with a mentor who helped me as I was fixing my first bug. Even after my first patch got accepted, he willingly suggested other bugs that I can work on. The community felt very welcoming, and this definitely helped to attract and retain new contributors.

#2 Always write clear documentation for your code

I observed that the documentation in the codebase is very extensive. For instance, in this part of the code, the documentation not only mentions why certain things are being done, it also mentions related bug numbers that the person should refer to. This is helpful especially because the codebase in Mozilla is extremely huge, and it is impossible for someone to always keep track of all the code changes.

Suggestions for TEAMMATES:

From contributing to Mozilla, here are some ways practices that TEAMMATES can adopt.

#1 Have a communication channel for the public

As for now, the main communication channel used is Slack, and it is only for contributors from CS3282. It could perhaps be useful to allocate a separate Slack channel that is open to public so that new contributors can communicate directly to the maintainers. Not only would this make newcomers feel more welcome, it can also better retain new contributors so that they will keep contributing to TEAMMATES.

#2 Having mentored bugs that new contributors can work on

Currently, TEAMMATES encourage new contributors to work on d.FirstTimers issue so that they can familiarize themselves with the codebase and the workflow, then move on to more complicated bugs. However, some of the first timer issues such as updating the user-map may not suit new contributors who are already quite experienced and are looking for more challenging bugs. To cater to these people, perhaps TEAMMATES can have a new label for mentored bugs: bugs that are challenging but also comes with a mentor so that more experienced new contributors can work on them.

Suggestion for Mozilla:

Perhaps Mozilla can slowly switch from using mercurial to using git as a VCS, because the number of developers and projects using mercurial is much smaller than those who use git. This will definitely be easier for new contributors to start getting involved in Mozilla.

RAHUL RAJESH

Project: Exercism

My Contributions

What is Exercism?

Exercism (https://exercism.io) is an online open-source coding platform that offers coding practice and mentorship for over 40 programming languages! As of August 2018, Exercism has 1,700 contributors and 700 mentors.

Contributing to Exercism

Key Takeaways

Exercism is a good choice for new contributors. Exercism has a nice variety of issues for newcomers to contribute to and excellent documentation to match as well. A few ones someone can start contributing to this repository include:

Improve existing tests for an exercise
Convert an existing exercise to another language
Create your own exercise
Improve grammer/phrasing for exisiting exercise
Help maintain or fix bug in build systems/tools

As you can see, there is a range of issues one can work one. The issues can range in difficulty from trivial to really challenging. I chose to do one simple Pull Request(PR) to port an existing exercise to C++ and I did a slightly harder PR which involved creating a brand new exercise. There have been many learning points throughout this process. I will list some of the more important ones and eventually compare them with my internal project, Teammates.

1. The more the merrier...or is it?

Exercism has over 40 programming languages and has a repository specifically for an exercise. There is one master repository that handles the canonical data for all the exercises. There is a certain elegance to how this project has managed to keep a decentralized system like this working. There are core team members working on each repository and each track has specific instructions on how to set-up and create new exercises.

My contribution to C++ for example uses CMake to test the code and has a specific format for the files. I knew this from the clear documentation they provided. The team responded almost immediately to my pull request and merged it in after a couple of seconds. It was all very smooth.

How does one manage such a decentralized system effectively? Exercism also definitely has its ups and downs.. but for the most part it does a fantastic job of syncing across the different programming languages for the various exercises. It is able to do so because of a strong team (some of them I believe are volunteers) who are willing to spend their spare time guiding new contributors and maintain the repository. More than just the technical aspects, I have learnt that it is the people who drive large open-source projects; people with a core mission and passion to work for a larger cause.

2. Pushing the difficulty barrier.... Code Quality/Checks

While I was doing the PR to port an existing exercise to C++, I realised I was just following a routine. Yes, I learnt about the contribution workflow and the development process behind Exercism. However, I could not help but wonder if this project had good quality control or stringent reviews. Majority of their PRs are small patches and I did not see much of this. As a result, I tried something different and implemented a completely new exercise.

This is a big deal. Mainly because a new exercise will be something that is going to be shared over all the 40+ languages. Every other language will be using your data and description. I submitted a PR to add a classic problem: the 0-1 knapsack.

Over the next few days, I was hit with a series of consecutive reviews. I had six people in total commenting on my PR. The reviewers were thorough. Some wanted to be convinced on why this exercise was needed. Others tore my description/tests down and asked those parts to be updated.

Overall, I have to say this project enforces a high standard for their exercises. What really impressed me was how 6 people reviewed by PR without having too much conflict or overlap. Each of the reviewers took the time to sit and read through the exericse/problem and point out subtle details. One of the reviewers updated some parts himself and pushed into my branch! (He told me the changes he made and his rationale) What i have learnt from this is as a reviewer, it is important to justify your comments and also convince the person contributing on why a change is needed. If you look at my PR on this above, you would realise that all the reviewers justified their comments and even asked for my opionion on changes. This is how you encourage new contributors to contribute further and grow your developer teams. I look forward to contributing more to them.

3. The bigger picture - Teamates vs Exercism

Now that I have covered some of my major takeaways, it is important to take a closer look at how my journey with Exercism compares with my internal project Teammates.

a. Encouraging development from the outside

Teamamates does not do a good job with encouraging new contributors as compared to Exercism. Of course, this is not a fair comparison considering teammates is still undergoing migration and there are specific deadlines to meet.

However, in the long run, I feel Teammates should strive to be inclusive to any external developer. This means improving our documentation and opening doors to a large variety of issues for one to work on. Similar to Exercism, Teammates should have a path set to allow new contributors to rise up the ranks and perhaps even become one of the core team members.

A more convenient set-up and testing framework would be ideal as well. Exercism has make files and tools to allow developers to quikly start contributing.

b. Strive for innovation and try to look past the conventional path

This is a strong point. However, what I really want to say is that Teammates sometimes suffers from a lack of innovation. We follow what we are told to do and follow tasks simply based on protocol. There is not much room for innovation and in fact, there is very little encouragement to come up with newer ideas.

Exercism leaves room for someone complemetely new to come in and start something. I came in with a brand new exercise and I was encouraged by the team. Teammates should also look to encourage innovation. It is only by having people who can look past the ordinary path, can growth be achieved. Many times I feel that new ideas are shot down too quickly or are looked past citing reasons like this is how it was done in the past etc. I hope this will change one day in the future!

Note: Exercism is also not perfect and it has its flaws. It is an established project and thus, there is not much change going on. Teammates is in migration and is undergoing massive change. Any comparison is not completely fair.

RONAK LAKHOTIA

Project: Exercism

Contributions

Links to getting started with Exercism

Observations about the project

About the Project - Exercism is an online platform designed to help you improve your coding skills through practice and mentorship. Exercism provides you with thousands of exercises spread across numerous language tracks. Once you start a language track you are presented with a core set of exercises to complete. Each one is a fun and interesting challenge designed to teach you a little more about the features of a language.

1. It provides you with thousands of exercises spread across numerous language tracks. I decided on contributing to Exercism because of the number of language tracks that a developer can choose from. Since I am most comfortable with Java, I made pull requests to the Java Learning Track. One can find other languages like C++, Python, JavaScript and many more.

2. Exercism uses tools like Exalysis that automatically runs the tests on a solution and makes some helpful suggestions based on static analysis of the code for common errors and patterns. They even have a Command Line Tool for interacting with the website from the local environment.

3. The project workflow is smooth in general. Mentors are always ready to help new developers during the initial stages. The exercism community is active and there is an online chat room too where mentors and developers can discuss their ideas. For instance, while working on one of the PRs, there were a couple of mentors who suggested changes to my implementation. They did so in a nice and helpful manner which I feel is important for attracting new contributors to an open-source project.

Key Takeaways from this Project

1. Suggesting Alternative Viewpoints - An important thing I learned while contributing was to not be reluctant in suggesting alternative ways for a particular implementation. It is a good practice to discuss ideas with the mentors and eventually settle on the best path.

2. High Quality Code - Writing code that is readable to other developers is very important. In fact documentation in the form of comments should be minimal. Most Exercism projects encourage contributors to write code that is readable and does not need the aid of comments.

3. Interaction with fellow developers - Exercism has a dedicated communication channel that allows developers to collaborate and discuss ideas/solutions. It is a great way to network and also provides you with an opportunity to communicate with mentors who have experience in the industry for a long time.

Improvements for Exercism

1. The documentation for Exercism could be improved. Making use of architecture diagrams or perhaps other visual aids should be included to help new developers get used to the codebase.

2. Perhaps the issues could be labelled to help newcomers. This practice is followed in TEAMMATES and can be a good addition to the Exercism project.

Project: JabRef

Contributions

Links to getting started

Observations about the project

About the Project - JabRef is a cross-platform citation and reference management tool. It helps you collect and organize sources, find the paper you need and discover the latest research.

1. For every change made, updating documents is a must and it is a part of the PR checklist. This practice must be followed before a PR gets merged. It enforces good standards of documentation to be followed consistently.

2. The review process requires at least two senior devs to approve your PR before it gets merged. This means the code reviews will be thorough as was the case when I submitted PRs to the project.

3. The issues have proper labelling, each of them categorize according to the description and which part of the application it is relevant to. This is very important to allow new contributors to get used to the environment and make them feel at ease.

4. The project uses tools like Codacy and DEP. Codacy automates the review process and eases development workflow. It has been made a part of the CI workflow where if your PR fails certain thresholds of code quality, the build will fail. DEP is a bot that checks for PR dependencies and tells the developer if other issues need to be resolved before the current PR can be merged. This is a good way to manage a particularly large project.

Key Takeaways from this Project

1. Emphasis on Documentation - An important takeaway was that, JabRef encourages contributors to keep updating the documentation with every PR, which is quite interesting as I have not come across his practice in other projects. Such practices can be enforced by other OSS projects too.

2. Asking for help - The JabRef community is big and help is readily available. Contributors are encouraged to discuss ideas and methods of implementation. They even have a gitter channel to welcome new contributors where once can post queries.

Improvements for JabRef

1. JabRef can perhaps can improve their documentation of setting up the project. It will help the newcomers ease into the new environment. Currently, it seems a bit convoluted. Perhaps, having a cleaner workflow will make it easier for new contributors to set up the project. Another possible addition could be to use video tutorials to make it easier for contributors to follow the set-up process.

Project: apps-android-commons

Contributions

Fixed lint errors

Links to getting started

Observations about the project

About the Project - The Wikimedia Commons Android app allows users to upload pictures from their Android phone/tablet to Wikimedia Commons.

1. The project workflow is easy to follow and mentors are always ready to help. The senior devs guide new contributors and are patient throughout the process.

2. Since the project deals with a mobile application, each change made in the PR requires developers to upload screenshots. This is to ensure that no regressions have occurred due to your changes. This was unique for me because I have never worked on a Mobile application before.

Key Takeaways from this Project

1. Testing your code - Mentors emphasize on the importance of testing. Your changes should have relevant test cases before it is up for review. A lot of importance is placed on the code coverage of your PR.

1. Automated review process - The project makes use of Codacy to automate the review process in the initial stages. Metrics are set failing which the PR build will fail. I think it is a great way to enforce good engineering practices.

Suggestions for TEAMMATES

1. A practice that TEAMMATES could adopt from Exercism is to have a dedicated channel for new developers coming into the organization. This can really help in the on-boarding process and ease new developers into the new environment. An advantage of this is that the communications carried out in Github can be taken to slack channels where the process will be faster. It also gives new contributors an opportunity to ask clarifying questions.

2. Another area that TEAMMATES can work on is to grow the number of students running the organization. It might make the development process faster if more mentors are on-board to drive the project forward. The logistic constraints are understandable which is why incoming contributors must be encouraged to stick with the organization and help maintain it as the user base continues to grow.

3. TEAMMATES could consider using automated tools for code review. This will help ease the workload on senior devs by pointing out common error patterns and improvements in a PR. As a side note, TEAMMATES can also start a technical blog to show potential users and developers the new changes being worked on. For instance we could mention about migrating to Angular, following a REST architecture, etc.

TAN HENG YEOW

External Project: Firefox Developer Tools

Contributions

Summary of bugs worked on
Summary of other contributions made e.g. bug triage, raising bugs, performing code reviews, technical assistance, helping contributors etc
Profile page gauging level of activity

Contributing workflow

There is a comprehensive developer documentation that one can consult for working on Firefox Developer Tools (FDT). I will give a summary of only the necessary steps required for the typical contributing workflow.

Set up a Bugzilla account. Bugzilla is Mozilla's bug tracker.
Use Mercurial as the Version Control System (VCS), pull and build the code.
Find suitable bugs to work from this page. You can also use Codetribute to find good first bugs to work on.
Run browser mochitests to check for regressions after making code changes.
Use Arcanist or moz-phab as a command line tool to manage code reviews performed in Phabricator, a suite of web-based software development collaboration tools.

Learning points

Throughout my journey in contributing to FDT, there are many learning points that helped me become a better open source contributor, which are also beneficial for other engineers alike.

Produce clear Steps to Reproduce (STR)

The STR can refer to steps on reproducing a bug or steps of how one goes about debugging or testing code manually. This is especially important for projects like FDT where it involves a variety of different expertise. They include people working on different panels of FDT, people working on front-end and/or back-end of FDT, people working on the networking platform, people working on localization/accessibility, people working on other parts of Firefox and external contributors with different backgrounds etc.

Different expertise possesses differing context of the issue at hand. As a result, without a clear STR, it would be hard to involve different expertise to collaborate together to solve an issue.

Take for an example this patch which involves the back-end platform team exposing an API to the front-end team to use. As both the front-end and back-end codebase's size are significantly huge, different people in different teams may have little idea on how things work specifically in each other's domain.

A good example would be this comment where it clearly describes the STR of how the code is tested so that expertise from the other team has a better idea of the context of one's approach in performing the manual test.

As a general rule of thumb, I learned that we should be as verbose as possible in giving STR, to the extent where we put ourselves in the receiving party's shoes and assume they do not have any prior knowledge.

DevOps expertise is crucial

FDT is a complex web application embedded within Firefox, both of which have significantly large codebases. A dedicated system Treeherder is built to handle Continuous Integration (CI) data, which similar to the Travis CI that we use in NUS-OSS.

Reviewers would normally push ongoing patches to Treeherder (with an estimated of ~1 hour of build time) to check for regressions before reviewing the patch. Contributors who fixed a few bugs are allowed Level 1 Access, which enables them to push their patch to Treeherder to check for regressions.

With proper CI in place, reviewers can ensure that the submitted patch does not cause the software's build process to fail. This is crucial where the consequence of regressions is very heavy as a small breaking change might cause the Firefox browser to malfunction.

With millions of people pushing new code/features to the same codebase every day, the importance of DevOps team is obvious here because they are responsible for landing the code in the codebase while ensuring that the codebase stays healthy.

Even though one can rely on automated CI software that is managed by external vendors, having DevOps knowledge would ensure that a team can build, test, and release software faster and more reliable as the product scales.

This is a case study from Netflix on how DevOps is practiced in the company.

Using Test-Driven Development (TDD)

Almost every bug that I worked on for FDT required me to write a test to verify its functionality. Occasionally, I'm required to make changes to other test files as well due to the code changes I made.

The reason for writing tests is because regression testing is needed to ensure that we do not break other features present in the codebase during the build process (related to the previous point above on DevOps).

Tests are heavily encouraged in software that utilizes DevOps, thus it would be more efficient for developers to use TDD.

Instead of thinking of writing tests as an afterthought, reversing the process would result in increased productivity.

Having an active international community of members result in higher contributor retention rate

FDT has a dedicated Slack channel which has different channels catered for different panels and a general channel catered for everyone.

At any point in time, there is a high chance that one's query is answered by a member that is online. Over time, this behavior encourages people to give back because they have received some sort of help from others in the same way too.

Also, by having an active community of members giving back their knowledge, it encourages new contributors to be less reluctant to ask questions for fear that they might be asking "stupid" questions or just embarrassed that they will be judged based on what they ask.

Furthermore, actual Mozilla employees communicate with other contributors in the same channel as well and often aid new contributors with basic queries. This act also reflects well on the community on welcoming new contributors.

Transferable knowledge

Throughout my journey in contributing to FDT, there are a few points that I feel TEAMMATES can adopt as well.

Have a list of experts in certain areas of the codebase

In FDT, there are owners for different panels. They are the main person(s) to go to or get reviews from when working on a respective panel.

Even though the scale of TEAMMATES may be smaller, there is still an incentive to have this type of structure. In the past, issues are grouped based on different areas of the TEAMMATES for e.g. f-Results, f-Questions, f-Profiles etc. Also, we have past area leads who led certain areas of TEAMMATES.

However, the recent ongoing migration to v7 requires most contributors to work with multiple areas of TEAMMATES and issues are mostly grouped according to front-end and back-end.

We can definitely consider bringing back this structure once the v7 migration has been completed. As the project gets bigger, it is hard for one to know everything, with the exception of project leads which require years of experience.

New contributors can start off understanding certain areas of TEAMMATES and then slowly branch out to more areas of TEAMMATES. They can then choose 1 or a few areas to be an expert at after working with the codebase for some time. Afterward, they would help in handling reviews, suggestions and/or provide directions for features related to their area of expertise.

Maintain a technical blog

FDT maintains a technical blog which highlights their roadmap, new features and also retrospections.

We can set up a technical blog for TEAMMATES highlighting our milestones and achievements based on the releases we made. There are a few benefits to doing this.

Firstly, it provides students a chance to improve their technical writing skills and also share the work that they have done with more people.

Also, having a technical blog provides a platform for potential contributors to be aware of TEAMMATES, the tech stack we are using and also the impact that we are making for educators worldwide. This allows TEAMMATES to get noticed by new contributors and might result in a potential source of constant contributors apart from Google Summer of Code (GSoC), CS3282 and summer interns.

Lastly, having a technical blog would also reach out to a wider range of audience. Software rarely gets noticed through GitHub repositories. Having a platform that reaches out to a wider range of audience could bring in more users, potential sponsors and also opportunities for collaboration.

Online video call meetings

In FDT, they hold team weekly video calls with meeting notes recorded. This might be hard to reproduce exactly for TEAMMATES due to the difficulty in accommodating to everyone's schedule.

However, one recommended approach I can suggest would be to hold a video call meetings for significant milestones that involves external contributors too. Right now the only meeting that TEAMMATES does is the code sprint to get everyone up to speed to develop for TEAMMATES during CS3282. Even so, they are catered for our own NUS students.

External overseas contributors rarely get a chance to deal with significant milestones that the TEAMMATES core team is handling with the exception of GSoC students where they take on a significant project over the summer.

The retention rate of past GSoC students is low, as well as external contributors who often fix a few bugs for coursework and leave afterward.

By having video call meetings for significant milestones that TEAMMATES is working on, we can also involve external contributors so that most of the people that are committed will be on the same page and would not feel left out.

I feel that retaining external contributors would be a good first step in getting more mentors to handle more potential CS3282 students. Over time, I believe retaining external contributors would form a virtuous cycle of increasing the number of contributors for TEAMMATES.

Issues that are harder than first-timer issues that involve more mentoring

From my observations, our d.firstTimers issues are a lot simpler than other projects but the transition to work on d.Contributors issues may be huge for some contributors.

For contributors that require more assistance and time in understanding the codebase, they would often give up after solving their first issue and then stop contributing. However, they might turn out to be effective contributors given more time to understand the codebase.

We can take inspiration from FDT's profiler where both their good-first-issue and help wanted labeled issues involve instructions on how to complete the task.

Although finding the related files to change is part of the learning process, we can identify some of these bugs and provide clear instructions on how to proceed to work on it. This would give potential contributors more confidence to take on harder issues. As a result, the transition from a d.firstTimers issue to a d.Contributors issue would be smoother.

Active Slack channel that welcomes external contributors too

Right now our Slack channel only accepts interns and CS3282 students due to mentoring resources available.

The initial phase of mentoring these external contributors may require a lot of resources and there is no certainty that they would stay too. However, if we think of this issue in another perspective, having external contributors invited to the Slack channel might benefit TEAMMATES in the long run.

Firstly, it allows current CS3282 students to have a chance to mentor external contributors. New contributors to the project helping each other sparks positive interactions and would contribute to an increased retention rate of contributors. Over time, the interaction might scale up to the level of what FDT has currently, which is a win-win situation for everyone.

Also, there are little drawbacks to accepting external contributors even if they do not become active contributors in the end. That would be almost equivalent to having little to no external contributors in the first place.

We can have a separate TEAMMATES public channel to start the ball rolling if there are concerns integrating this suggestion into the current channel we have now.

Areas of improvement for external project

Provide more architectural diagrams

Most of the documentation is text-based which might be hard for new contributors to follow. Architectural diagrams or diagrams, in general, would help contributors in understanding the codebase in a visual manner, similar to what TEAMMATES have currently done.

In addition, diagrams also provide more experienced contributors an easier reference to work with. Furthermore, it can be used to facilitate technical onboarding of new members/employees.

Incrementally move to a more well-known VCS like GitHub

The act of moving code to GitHub attracts more contributors as the code would have more visibility given that more projects are now on GitHub.

Also, most people are familiar with Git rather than Mercurial, so that adds up to attracting contributors.

There is an ongoing initiative to do that as seen by the debugger living in a GitHub repo, so that is definitely a step in the right direction.

WANG JUNMING

Project Exercism

My contributions:

Observations:

Exercism is an online interactive tool for learning new programming languages. It supports more than 40 programming languages. Each language has its own exercise repo, which contains a set of exercises to improve your skills. Each language repo is maintained by some senior developers(all volunteers), who is in charge of maintaining, updating and reviewing new PRs.

Overall, the project's documentation is well-written. They have general documentation about how to get started to contribute, which can be found here. This is because although those repos differ from language to language, the general workflow of contributing is almost the same. It preserves the consistency across different repos. And make it much easier to contribute across different language repos. Apart from that, different repos also have their own supplementary documentation, which includes more detailed guidance and specification to help newcomers to get started. They have also created a separate repo named problem-specifications, it includes all the information about the exercises you can implement. In addition, exercism has kindly developed a tool configlet, which is an integrated tool that could generate templates, lint, upgrading etc. It automates all the tedious works and let developers focus more on the development. However, unlike TEAMMATES, they never use any graphics in their documentation, I think including some proper diagrams will make newcomers to understand the project structure more easily. Lastly, when I worked across different language repos, I found their labels for issues are inconsistent across different repos. Each repo has its own set of labels for issues, and some times similar labels can mean different things in different repos.

The contribution workflow is similar to TEAMMATES as can be found here. One thing I liked about exercism is that they have strict regulations about commit messages, they have even kindly included some article of how to write good commit messages, I really enjoyed those articles and learned a lot from it. Recall when I was working on my first task of TEAMMATES on API consolidation, the commit messages are just a mess. However, I gradually learned how to organize the message after reading those articles. Organizing commit messages not only make the reviewer's life easier, but also shorten the review process since everything becomes clearer.

One thing I observed is that many large-scale open source projects(not only exercism) tend to make their project easy to get started for newcomers. Either by writing high-quality documentation, provide a tool for automating tedious work or label some first-timer issue. All those encourages for contributing. Although TEAMMATES has well-written documentation and labeled first-timers issue properly, I notice it does not have many volunteered contributors. One key reason might be its relatively complicated local set up instruction(although is well written). Nowadays many projects are migrating to Docker, which makes local set up as easy as one command. Should TEAMMATES apply docker also?