Contributing | Code Contributions & Issue Tracking | Fluid Attacks Help

Contributing

Idea
Make sure to read other contents in the Start here section.
Please submit bug reports, feature requests, or general feedback to our Bug Tracker on GitLab or to our Support Email.

Since most of the contributions made to the project are code, from now on, this document explains the code contributions process.

Guide for creating issues

GitLab issues are the first step in continuously improving and correcting our products. That is why we have developed this comprehensive guide to provide the necessary steps to create an issue effectively.

Below, we will explain everything you need to know when creating an issue:

Who can create an issue?

As our open-source code, anyone with a GitLab account can create an issue. 

Issue title

The title of an issue is essential to clearly and concisely communicating what you want to accomplish. It should be descriptive enough for readers to understand it quickly. The syntax of issue titles is as follows:
[Product] Brief Description of the Problem
[Skims] Check AWS ELB listener on http

Type

Issue: To add new features to the product.

Description

Here, you can select a template that best describes the issue. The templates are as follows:
  1. Bug: Refers to a bug or error affecting a product’s functionality or performance.
  2. Feature: Add a new functionality in one of our products.
  3. Onboarding Steps: Create a guide for new developers with internal and external links to support more accurate access to information.
  4. Request for comments: Propose and discuss new standards, protocols, or features, where comments, suggestions, and observations from the community are invited before finalizing the implementation.
  5. Skim method: Create a new Skims method.
  6. Ux prototype: Generates a proposal from a UX prototype.

Assignees

The assignment of the person in charge of executing this issue is given.

Labels

The purpose of these labels is to categorize and organize the issues, providing a quick and visual way to identify the content and status of the elements in the project. The labels allow better management, tracking, and filtering of the elements, facilitating collaboration and decision-making within the development team. So that you know which labels to use, read their definitions in GitLab.

Priority Labels

The following labels indicate the severity level of an issue based on its impact on the system or user experience. These labels help the team prioritize work and establish response times. Each issue must have exactly one priority label:
Priority LevelDescription
CriticalReserved exclusively for incidents. Applies to situations that affect the system's security, availability, or integrity and require immediate attention.
HighUsed for failures in key product functionalities that prevent users from completing important tasks. While not classified as incidents, they have a high impact on the user experience.
MediumApplies to errors in non-critical functionalities. The system remains usable but may exhibit partial interruptions, unexpected behaviors, or require workarounds.
LowRefers to minor issues that do not affect overall system functionality. These are usually related to visual aspects, content errors, text adjustments, or other low-priority details.

Steps

Code contributions are done using the Merge Requests feature on GitLab.

As the Author of the contribution, please read the following steps and apply them in your day-to-day:
  1. Configure your Development Environment.
  2. Make sure that your contribution has an associated issue in the bug tracker, or create one.
    1. Make sure that you understand the motivation behind the issue, the problem it is trying to solve, its impact, its trade-offs, and that it makes sense to implement it as described.
      2. Issues are not set in stone; make sure you iterate on this as many times as needed, and edit the issue as you go.
    2. Make sure you enumerate all of the components that will be impacted by the issue.
    3. Make sure the issue has received sufficient feedback from the Code Owners of the components impacted by the issue before starting any implementation.
    4. Don’t be afraid to ping the author or the Code Owners for clarification. Excellent developers do excellent requirement analysis.
  3. Code, and:
    1. For each of the issues’ impacted components and their corresponding component page:
      1. Keep their docs updated.
      2. Make sure you follow their guidelines.
      3. Make sure you don’t violate their Public Oaths.
      4. Keep their architecture updated.
      5. Add any missing information to their documentation. We want to be able to level up and empower other developers to write code autonomously and with confidence, but we cannot do so without documentation. Documentation is important; make yourself replaceable.
    2. Make sure that your implementation is sufficiently tested:
      1. By adding automated tests to the CI/CD.
      2. By manually testing the functionality.
      Feel free to use feature flags if appropriate.
    3. Make sure that you update the End User documentation, particularly the Platform section.
  4. Open a Merge Request, and feel free to ping, assign, or send a direct message with the link to the Code Owners of the issue’s impacted components.
  5. Go back to step 3 until the issue is completed.

Review process

We conduct code reviews using the Merge Requests features on GitLab, and discussions should happen in the open, either on the Issue, the Merge Request, or the team-wide communication channel.

Reviewers are selected by the Head of Engineering or the Developer who created the Merge Request. In general, a reviewer reads the code, reviews the related issue, and then examines the files modified by the Author.

A reviewer must have the following mindset when performing a review:
  1. Transferring knowledge to the author.
    2. This can range from a small code suggestion on how to make the code more maintainable or faster, to suggesting a library, reminding them of the guidelines, suggesting a way to organize the code, or signaling fundamental architecture/bugs/security problems that should be considered with the current approach the author is taking.
    There are 8 quality characteristics of good software. Help the author think about all of them.
  2. The author probably knows more than the reviewer.
    3. The author is the one in the field, touching the code and seeing the problem first-hand. Always give the benefit of the doubt and start the discussion with a question, rather than an affirmation that things are wrong. There is a chance the reviewer is not seeing the full picture.
  3. Neither the reviewer nor the author has more authority.
    4. We are all Developers.
    When proposing something, make it sound like a proposal and not like an order. If what a reviewer says has value, the author will probably accept it and apply it right away. If a discussion arises, keep it healthy, constructive, and argument-based. Either the author is seeing something the reviewer doesn’t see yet, or maybe the reviewer is seeing something the author doesn’t see yet. This “aha” moment unlocks learning, and a safe environment to argue is key to good decision-making.

  4. Minor improvements or fixes can come later.
    5. If merging a Pull Request adds more value than closing it, go ahead and merge it. Just take note somewhere so that the author reminds amending it later. Also, don’t be too picky, especially about things that are subjective, like style, formatting, or those that are too minor to even pay attention to (like a typo in a comment).

  5. Avoid reviewing or approving Merge Requests that fall outside your domain knowledge or expertise.
    6. It’s better to defer to someone with direct experience in the area to ensure a high-quality and informed review.
A reviewer must check:
  1. That the contributing steps have been followed, not only in the Merge Request, but also in the associated Issue.
  2. That the Merge Request adds more value than what it takes. This is subjective, but the 8 quality characteristics of good software are a good starting point.
A reviewer should accept a contribution if it’s been made according to this document.

Code Coverage

Codecov is an invaluable tool for evaluating the quality and effectiveness of unit tests in our products. Here’s a detailed guide on how to interpret and utilize the reports it provides:
  1. Accessing Reports: Codecov coverage reports are available for each Pull Request and can be accessed directly from the GitLab user interface.
  2. Coverage Interpretation: The coverage report provides an overview of the code being tested by our unit tests. It is represented as a percentage, where 100% means all lines of code are being executed by our tests.
  3. Identifying Untested Areas: Review the coverage report to identify code areas that have not been adequately tested. These areas may be critical points requiring further attention in terms of unit testing.
  4. Coverage Trends: Codecov also offers insights into coverage trends over time. Use this information to evaluate whether our product’s coverage is improving or declining over time.
  5. Corrective Actions: If areas of code with insufficient coverage are identified, collaborate with the team to implement additional unit tests and improve coverage in those areas.
By effectively using this tool, we can ensure the quality and stability of our code over time. This practice also fosters a test-focused development culture throughout our team.

Integration of Coverage Results in Codecov

In our development workflow, each time tests are run in our continuous integration (CI) environment, artifacts containing coverage results are accumulated. These results are generated by tools such as pytest, jest, and cypress, providing a detailed view of both unit and integration test coverage.

At the end of this process, a dedicated job for each component uploads these coverage results to Codecov. This job is presented in each of our products. For example, in the case of Integrates Back, the job is located at integrates/nix/pkgs/integrates-back-coverage .

Additionally, Codecov provides information about coverage deltas, showing changes in code coverage between two consecutive test runs. This allows us to quickly identify which code areas have been affected by recent changes and ensure they are adequately tested.

You can access the coverage reports and corresponding graphs at the Codecov page.

This integration ensures that we maintain high standards of test coverage in all our products, contributing to the overall stability and quality of our code.

Progress report

This is a quick guide on what information is expected in a daily progress report:

What did I do today:
  1. Current milestone(s), please include the corresponding URLs.
  2. Brief summary of tasks completed (e.g., “Fixed bug in login module”).
  3. Reference issues or tickets worked on (e.g., “Related to https://gitlab.com/fluidattacks/universe/-/issues/15624”).
  4. Any blockers encountered and how they were resolved.
  5. Collaboration: meetings, chats, asking for help, or supporting others.
  6. If applicable, use the ETA model when the task can be broken down into multiple, similar subtasks that allow for measurable daily progress toward a clear objective. The ETA should be calculated based on Colombian business days. Use this calculator as a reference.
  7. Include reviewed and approved MRs.
What will I do tomorrow:
  1. Tasks you plan to work on or continue (e.g., “Start implementing new resolvers”).
  2. Related issue or ticket ID (e.g., “Will focus on https://gitlab.com/fluidattacks/universe/-/issues/15624”).
  3. Objective for tomorrow — be specific (e.g., “Objective: Complete initial testing of the new resolver.”).
  4. Dependencies (e.g., “Waiting for implementation of new database table”).
I would need help with:
  1. Clarification on a task, requirement, or issue (e.g., “Need clarity on validation rules for XYZ input”).
  2. Unresolved blockers.
  3. Peer review or a second opinion on a solution you’re not confident about.
  4. Coordination needs (e.g., “Need to sync with the design team on the new visuals”).