Contributing

These instructions have been modified from LumenPnP’s contribution guide, who’ve paved the way in open hardware projects!

We are very grateful that you’d like to help out the project! FBRC can use all the help we can get in developing an open-source battery.

What you could contribute to depends on your interests, skills, and the current project needs.

Right now we need as many people as possible to try to reproduce our work! Build your own kit from the instructions! Even just 3D-printing the parts and assembling it without testing the electrolyte is helpful. Tell us what does/doesn’t work and let’s improve the build process and documentation.

Another place to start is in the issue trackers of our repositories, for example, our kit. Look for issues that are marked “good first issue”.

If you are not sure how you can help, please contact us through email or the forum and just introduce yourself and your capabilities/interests! We are happy to help you find a way to contribute.

There are two areas to contribute in that have more barriers than the rest: real-life testing of chemistry and hardware.

For chemistry, you must have the interest and prior training—there are chemical risks involved, and we aren’t responsible for anything that might happen as a result. We welcome anyone who wants to repeat our results and further investigate the chemistries and operating conditions.

For hardware, you need to have access to hackerspace-style equipment: an FDM printer that can print polypropylene, ideally a laser or vinyl cutter to cut gaskets, a soldering iron, and things like that. There is still a lot of testing and validation you can do even just running the system with water instead of a real battery electrolyte. Getting our system to be repeatable and robust, leakproof, well-characterized and controlled, are all possible without exposing yourself to chemical risks.

For everything else, you can contribute with a computer and an internet connection!

Getting Set Up

Aside from cloning the repository, there’s a few things to install and register for. We’ve chosen cross-platform software, so you should be able to contribute regardless of your OS:

  • FreeCAD

    FreeCAD is our mechanical CAD package. Its scriptability and offline support make it ideal for managing with git and automating tasks. Make sure to install the latest stable release. Install the Fastener workbench as well.

  • KiCAD

    We use KiCAD for all of our schematics and (eventually) PCB designs. Install the latest stable release, not the nightly build.

  • Codeberg (Git)

    We host our repositories here to do version control with Git. You need an account here to make contributions to our repositories and file issues. It’s free!

  • Git LFS

    We use Git LFS to make sure we don’t have merge conflicts with FreeCAD files. Install it with the link and run git lfs install to set it up with your account.

  • GitBuilding

    We are using GitBuilding to document our cell testing processes and generate BOMs for the entire process. Install and run gitbuilding webapp in the project directory and navigate to the project documentation in the browser-based GUI to edit and make changes.

  • The forum

    We use the forum to discuss changes and coordinate work.

  • Quarto (for the website)

    Quarto is a scientific and technical publishing system based on Markdown that can render static websites with features interesting to researchers, like code notebooks. It handles references easily and we would like to implement functionality where data files generated from FBRC cells can be processed in-browser on the website for simple and fast data analysis and archiving.

Once you have the relevant software installed, make a fork of the repository in question. Then, clone the fork to your computer.

git clone --recursive git@codeberg.org:YOUR_USERNAME/RFB-dev-kit.git

Making a Contribution

Our repositories operate under a feature-branch methodology. This means that work for an enhancement or bug fix happens in a separate branch made specifically for that change (or series of changes). Individual contributors make changes in their forks, and merge them into the main repo’s feature branch. Once the feature branch is done, it’s then merged into main once it’s complete. After the merge, the resultant commit is tagged with a new release number. A description of this git methodology can be found here.

We are using Git for some things it’s not designed to be used for, so we have a very considered branch methodology so that things can work well together. Please be sure to follow the guidelines below.

CAD (and locking)

When working with text, git does an excellent job handling merging two separate versions of a file. However, we are using git to track CAD files where a merge process is much less simple. To solve this issue, we use Git LFS (Large File Storage).

Git LFS is a tool for tracking and managing large binary files using git. We use it mainly for the lock feature it provides. Merging FreeCAD and KiCAD files is technically possible given that they’re stored in plaintext, but completely infeasible. To prevent the need to merge them, we instead have one person lock the source file before starting editing and until after merging so no conflicts arise.

Note

A rough video of cloning a repo, opening in FreeCAD, and making changes can be seen here as an example.

We will update this section with instructions on how to lock files once a need arises. Eventually, we may implement a CAD-staging branch similar to Opulo’s LumenPnP.

Docs

Docs are easy to handle in git! Docs are in the docs subfolder of our repositories and the source Markdown files are rendered with GitBuilding and pushed to the pages branch of the repository as a static site.

Making a Change

Now that you’ve cloned your fork to your machine and have some files locked, it’s time to get going! Make sure that your fork is up to date with the main repo (you can see how to do that here). Checkout the relevant feature branch in your fork and go for it! Commit frequently with descriptive commit messages. Once you’re finished, push up to your fork and file a Pull Request. Be sure to tag any relevant issues that your PR is relevant to or solves.

Versioning

There are version numbers for releases, called build numbers. There’s a release every time a feature or bugfix branch is merged into main, and there’s a new tag on the main branch. Releases are tagged using a version number in the style of semantic versioning, where, in part number vA.B.C:

  • A uprevs indicate a large change in the project that could be backwards-compatibility breaking, or major releases with lots of significant updates. (e.g. changing the bolt pattern on an endplate or switching to a new sealing method—this changes things in lots of areas of the project, requires new parts to be machined, and is backwards compatibility breaking.)

  • B uprevs indicate feature adds, CAD improvements, and other moderate changes. These are backwards compatible.

  • C uprevs indicate small bug fixes, typos, or other small changes.

Standards

The following are standards that we adopt across the project. They help make things easier to build, reduce part count, and reduce cost.

CAD

  • All parts are modeled separately in their own .FCDStd file, and then put into a final assembly file.

  • Stick to Metric unless absolutely necessary to do otherwise (e.g. an off-the-shelf part only has 1/4-20 threading available)

  • Use the same type of hardware, e.g. M6 for small cells, whenever possible. This reduces unique part count.

  • Ensure that any fonts used in your FreeCAD files use a relative filepath. Absolute filepaths will not work on other computers. Make sure you’re only using fonts in the /lib/fonts folder in the repo.

Chemistry

  • We prefer to work by mass composition whenever possible, because it does not change as a function of temperature

Full Workflow

  1. Hop in the forum and chat about the changes you’d like to make. Be sure to include the issue number that your change will address. (No issue yet? Make one, and mention it when discussing.)

  2. Ensure that your fork is up to date with the main repo.

  3. Checkout the branch you’ll be making edits to.

  4. Make changes. Commit often.

  5. Push your changes to your fork on Codeberg.

  6. Close any issues that have been fixed by your changes.

Working With Issues

All feature requests, bugs, and planned enhancements are logged as issues in the repository. There are multiple different tags that we use to keep track of them. There are three types of tags:

Type: These indicate if it’s fixing an active problem, or an improvement. Either bug or enhancement

Discipline: These indicate what skillset is required to complete the task. All relevant from the following should be chosen: chemistry, hardware, CAD code, documentation.

Misc: These indicate an extra bit of info that can be helpful to filter by. help wanted and good first issue are helpful for folks looking to help contribute. requires validation and discuss indicate a bit of prototype, testing, or conversation needs to be done before work on the issue can begin. wontfix is for issues we’ve decided not to pursue. duplicate is for issues that already have an issue, and should be closed shortly after tagging as such. workshop feedback is from feedback that was received in-person at a workshop.

Contributor Covenant 3.0

Our Pledge

We pledge to make our community welcoming, safe, and equitable for all.

We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant.

Encouraged Behaviors

While acknowledging differences in social norms, we all strive to meet our community’s expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language.

With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including:

  1. Respecting the purpose of our community, our activities, and our ways of gathering.
  2. Engaging kindly and honestly with others.
  3. Respecting different viewpoints and experiences.
  4. Taking responsibility for our actions and contributions.
  5. Gracefully giving and accepting constructive feedback.
  6. Committing to repairing harm when it occurs.
  7. Behaving in other ways that promote and sustain the well-being of our community.

Restricted Behaviors

We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct.

  1. Harassment. Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop.
  2. Character attacks. Making insulting, demeaning, or pejorative comments directed at a community member or group of people.
  3. Stereotyping or discrimination. Characterizing anyone’s personality or behavior on the basis of immutable identities or traits.
  4. Sexualization. Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community.
  5. Violating confidentiality. Sharing or acting on someone’s personal or private information without their permission.
  6. Endangerment. Causing, encouraging, or threatening violence or other harm toward any person or group.
  7. Behaving in other ways that threaten the well-being of our community.

Other Restrictions

  1. Misleading identity. Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions.
  2. Failing to credit sources. Not properly crediting the sources of content you contribute.
  3. Promotional materials. Sharing marketing or other commercial content in a way that is outside the norms of the community.
  4. Irresponsible communication. Failing to responsibly present content which includes, links or describes any other restricted behaviors.

Reporting an Issue

Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm.

When an incident does occur, it is important to report it promptly. To report a possible violation, send an email to info@fbrc.dev.

Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution.

Addressing and Repairing Harm

If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident’s impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped.

  1. Warning
    1. Event: A violation involving a single incident or series of incidents.
    2. Consequence: A private, written warning from the Community Moderators.
    3. Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations.
  2. Temporarily Limited Activities
    1. Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation.
    2. Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members.
    3. Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over.
  3. Temporary Suspension
    1. Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation.
    2. Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions.
    3. Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted.
  4. Permanent Ban
    1. Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member.
    2. Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior.
    3. Repair: There is no possible repair in cases of this severity.

This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at https://www.contributor-covenant.org/version/3/0/.

Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/4.0/

For answers to common questions about Contributor Covenant, see the FAQ at https://www.contributor-covenant.org/faq. Translations are provided at https://www.contributor-covenant.org/translations. Additional enforcement and community guideline resources can be found at https://www.contributor-covenant.org/resources. The enforcement ladder was inspired by the work of Mozilla’s code of conduct team.