👋 Hello there! Thanks for your interest in contributing! 👋
The purpose of this guide is to ensure all contributors have a unified approach to contributing to all projects within the gliff.ai space.
gliff.ai is a small company aiming to help get healthcare and life science AI products regulated with a focus on privacy and security; fairness, accountability and transparency; all by keeping experts in the loop to ensure high quality outputs for real people and solutions across the world. Because the gliff.ai team is small, we look for the help of volunteer developers like you to contribute to our open-source code ensuring gliff.ai can have the best and biggest positive impact possible.
Each repository has one of two topic tags to help you and fellow contributors understand which repositories gliff.ai is open to contributions outside of our team. They are:
- contributions-welcome – We welcome all types of contributions on this repository!
- no-contributions – This repository does not accept most contributions unfortunately! However, an issue can still be raised if you recognise a problem you wish to bring to the gliff.ai teams attention.
👍🎉 Thank you from the gliff.ai team for your interest and hopefully taking the time to contribute! 🎉👍
Looking for something specific? 🔍
- Introduction
- Table of Contents
- Code of Conduct
- Create an Issue
- Create a Pull Request
- Linting, Formatting and Testing
- Commit Best Practices and Naming Conventions
- Assigning Reviewers Best Practices
- Labels
- Contact
All projects and contributors are governed by the gliff.ai Code of Conduct 📝. By contributing, you are expected to uphold this code to ensure a positive and welcome community space for all.
Please report unacceptable behavior
Our team uses 4 templates for creating issues across gliff.ai repositories, and we would appreciate you also using these and filling them out with as much detail as you are able to provide. The templates include:
- Bug Report – report any bugs whether technical or visual (the “bug” label will be automatically applied).
- Feature Request – request any new features whether technical or visual (the “feature” label will be automatically applied).
- Enhancement Request – request any enhancements whether technical or visual (the “enhancement” label will be automatically applied).
- Test Request – request a new test not currently available (the “test” label will be automatically applied).
NOTE: Please remember to first determine which repository the issue should be raised in, then search the gliff.ai repositories to ensure the issue you want to open is not already open or previously closed!
The process of reporting a found Security Vulnerability is different to the above. You should only report this problem to the team via an email report by contacting us at security@gliff.ai and we would apprieciate you also including as much detail as you are able to priovide. Please refer to the gliff.ai Security Policy 🔒 for further details, including a content guide to create an in-depth report.
NOTE: If you try to report a found Security Vulnerability via the normal GitHub issue process, you will be redirect to the gliff.ai Security Policy 🔒 instead of an issue template. So feel free to access the gliff.ai Security Policy 🔒 either which way suits your workflow!
The Pull Request template should be filled out as much as possible. Your pull request should include a summary of the changes you have made and your motivation behind them. Please list any dependency changes, added tests, documentation changes, database changes (if applicable) and complete our checklist to ensure you have completed all the necessary steps.
Please remember to first determine which repository the pull request should be created in, then search the gliff.ai repositories to make sure the pull request you want to create is not already open or closed!
After you submit your pull request, please assign 3 or less reviewers following our assigning reviewers best practices and assign any labels you think are applicable. Please also verify that all status checks are passing. If for some reason they are failing and you believe it’s unrelated to your change or unsure why, please leave a comment on the pull request explaining this and someone on the gliff.ai team will further investigate.
For linting and formating our team uses flake8 and black for linting and auto-formatting our Python code alongside pytest for our Python code tests, or eslint and prettier.io for linting and auto-formatting our TypeScript code alongside jest with react-testing-library for our TypeScript code testing.
For system and visual testing our team uses BrowserStack – specifically Automate with Selenium, and Percy Snapshots together to test at scale the platform works as antipicated.
Any further or alternative specifics and configuration files can be found in each of our repositories.
If you create a pull request, your contributed code will automatically be linted, formatted and tested by the GitHub Action we have set up. New code should always use the same linters and formatters the gliff.ai reposorities currently use. We would also really appreciate new code to come with new tests, where appropriate, to be run against all existing tests!
Our commit best practises encourage creating small and frequent commits with clear log messages while editing the source code. This ensures commits are focused and any changes are easily understood and revertible if something goes wrong.
Commit messages should indicate the type and include a short summary of the commit using the following conventions:
- feat: The new feature you're adding to a particular application.
- fix: A bug fix.
- build: Development changes related to the build system (involving scripts, configurations or tools) and package dependencies.
- refactor: Refactoring a specific section of the codebase.
- test: Everything related to testing.
- docs: Everything related to documentation.
- chore: Regular code maintenance and/or style changes/formatting.
For example, “feat: add new icon svg file” or “fix: lint errors”.
One-line commit messages are perfect for small changes, but larger changes should include a paragraph describing what has changed and what is its impact alongside.
The key rule with assigning reviewers is we maintain a maximum of 3 reviewers on a single pull request. This comes off our team learning from the State of the Octoverse 2021 report where this rule ensures fast reviews. Now the question is, who should you assign?
The gliff.ai team active on our various projects are known as the “techteam” and subdivided into 4 self-explanatory smaller teams:
- backend: Requests 2 random members from this 4 person sub-team.
- frontend: Requests 2 random members from this 6 person sub-team.
- ui-ux: Requests 1 specific member from this 2 person sub-team.
- documentation: Requests 2 random members from this 4 person sub-team.
As best practice we recommended assigning reviewers using which team(s) are best involved with the content and solution of your pull request (e.g. UI bug fix (frontend & ui-ux), or new unit test (backend)).
Each issue and pull request should be assigned one or multiple labels depending on the content. We actively encourage all contributors to attach labels onto any issues and pull requests they open to categorise tasks and problems, making it visually easier to find and understand which ever task or problem is being handled in each issue and pull request.
Our repositories have 7 label categories which are subdivided into their own labels.
Welcome (white)
- good-first-issue – Perfect for new contributors.
Update (light grey)
- dependencies – Pull requests that update a dependency file.
- javascript – Pull requests that update a Javascript code.
- python – Pull requests that update a Python code.
Problem (red)
- bug – Something isn’t working or looking right.
- question – Further information is requested and/or required.
Improvement (gliff.ai purple – #AE79FF)
- feature – New feature request.
- enhancement – New feature request.
- test – Anything related to testing or tests.
- deployment – Anything relating to deployment.
Release (gliff.ai cyan – #00DBFF)
Inactive (black)
These labels are mostly consistent across gliff.ai repositories^ to make it easier for everyone while working across multiple. If you forget this don't worry, when you open your issue or pull request each label has a description!
^ NOTE: the ROADMAP repository has its own unique labelling system.
Need some help? 🤔 Have a question? 🧠
Reach out to the gliff.ai team at community@gliff.ai or on GitHub.