We’re excited to announce a new resource for anyone interested in contributing to the TrueNAS WebUI project: our Contributing Code Guide! This short guide is everything you need to get started with WebUI code contributions, whether you’re fixing bugs or just exploring open-source development. This should cover everything you’ll need, from setting up your development environment to submitting pull requests.
We’re thrilled to have you join us in making TrueNAS even better. Every contribution counts, and contributors will receive a beautiful #FFD700-plated forum badge recognizing your contribution, as our thanks to you!
For my question/example: I just took the first wanted item in the list and in answering the ticket, I’d have to make the following assumptions and build a PR something like below (NOTE: I saw the class but I used a function for this swag-reply on purpose. Also note, I don’t know typescript so, this is essentially typed blind).
Basically, a new developer may not know what a typecast is and/or what floating-point mitigation is but developers (new and old, I guess) need a bit of guidance on best practices for the things project dev’s take for granted; like style, mitigations, hooks, etc… Do you have a style guide you can share? Another possible suggestion would be to develop the commit stds for these issues (not so they match the current style but to simplify the review process).
Do you want this style (and what should I be using if you do)?
// calculateProgressValue --
// @brief Calculates a progress value in whole numbers.
//
// @param current The current progress percent.
// @param total The total percent to calculate for.
//
// @return integer
//
// @example calculateProgressValue(job.progress.percent, 100);
function calculateProgressValue(current: number, total: number): number {
// XXX: Cleanup logic; toss error vs return 0 (adopt a proj std method).
const progress = 0;
if (current > 0) {
progress = (current / total) * 100;
}
return Math.round(progress);
}
...
// XXX: "if percent"? Should this conditional exist?
if (job.progress.percent) {
// PR:### @john &03.19.25 - changed float to int.
this.progressTotalPercent = calculateProgressValue(job.progress.percent, 100);
}
// XXX: What is this?
this.hideProgressValue = job.progress.percent === null;
...
Or something like:
// -This is not how a developer (sh/w)ould do this but let's roll with
// it for now.
this.progressTotalPercent = (job.progress.percent / 100) * 100;
If there is an issue we’ve already got a fix for, but no existing ticket, what is the process then? (I’d assume raise a ticket, but where that then goes to triage team, etc, not sure if it would be okay to raise a ticket and then immediately follow up with a PR)
As a general rule for patches against the Help Wanted List, try to match the style of the code surrounding the proposed patch. Then, make the simplest correct change (and test!) following that style that resolves and validates the issue. If the fix appears to require a significant refactoring of other existing code, then it probably never belonged on the Help Wanted List, or is possibly the wrong fix… Also, one issue fixed per JIRA issue, please. Fixing a small handful of issues “while I was there”, complicates reviews, documentation, and is likely to lead to rework requested by reviewers.
For future reference - process would be what? Raise a ticket, then a PR referencing it? Or try and keep contributions limited to what has been requested in the help wanted list?
I don’t want to waste engineering time raising pulls for small visual fixes that then need to be backlogged with a ticket, so if there’s a good process to avoid extra work for those at iX I’m all for it
Hi. Generally, the guidance is to pick tickets directly from the Help Wanted list. This ensures that we’ve given it a green light already, it just needs someone to pick it up and go. However, in a case where you find something to do in the WebUI that isn’t on that list (and also doesn’t already have a ticket in JIRA), the best thing to do is to start with creating the ticket itself. Then, by all means, reach out to the team on the ticket if you’re interested to make a fix for it. You could request it to be put on the Help Wanted list, even. Just be sure to communicate what your ideas are. The worst thing would be if we cannot accept your work for some reason (one example may be if we happen to know that a particular area of code will be completely overhauled soon, fixing an issue there may not make sense. There are many other scenarios, as well).
