Just to clarify: “fundamentally difficult” in my book means “design a new system from scratch”, but that does not mean that this idea would be easy. This is a hypothetical scenario for the purpose of discussing things, and it would take a lot of hard work across components to deliver.
Okay, but, if that task was “not hard” then why hadn’t iX not done it already? The middleware repo is one repo for both scale and core separated by a branch (merge the branch and push right?). Why would I, or anyone go through all the work necessary to implement a feature without a simple discussion with iX (even if it were as simple as a merge)?!
For another example:
Last night I just made a program (in c) that takes file(s) arguments and writes c code to reproduce those files and compiles it (think poor-man’s backup database replacement kind of thing). The code I wrote is dangerous (I mean code that should NEVER, ever, see the light of day) but will probably be used by me as a failsafe only because I know what it does and how to “use it safely given the conditions I need/have”. Should I just push this code to iX for inclusion into TrueNAS SCALE/CORE? I mean, that being an absolute horrible project idea, that no one besides me knows how to use properly, that could kill an entire system in milliseconds. …A ‘community effort’ needs honest, real goals with real definitions and to get those, a quick discussion with iX is needed (just going off half-cocked is a horrible idea and will fail!).
iX doesn’t want to/won’t talk. That means, they will kill any community effort.
Lots of effort. It’s not fundamentally hard in the sense that it would not be a novel system, and you have something to compare it against. More of a “throw competent devs at the problem for long enough” sort of problem than a “sit around a whiteboard discussing how to make things work” situation.
1 Like
No, I get it, and I agree on a fundamental level. But even that would require testing at every change; it would be a daunting task to say the least. And here’s the rub, why focus attention on a GUI when the underlying system will be dead in less than 5 months (at most)? The project would have to invest in its lifetime (get the base up to 13.4 or 14.1) first before investing in “new features”.
I asked Kris if there was a “new hire packet” to help learn the ins-and-outs of the repos but his reply was to “start at the build repo and work backwards”. This was either a brush-off or an indication that they will not share internal information. I spent a day or two and I was able to glean the build but when it came to the middleware and whatnot I just sort of gave up (the repo’s are just a slew–a mess–of branches) so a real effort would need to be made to get that all cleaned up and documented so a few people could actually work on them first.
Here is a start on some “community effort documentation”. Hopefully, this will be a useful start to get members involved. I have serious doubts, but I’ll just toss this rough draft out there to see if we get any bites.
This writeup could use some help in the form of “eyes-on” to fix any errors and mistakes. I have started this as a “general help wanted” document typical of most opensource projects but if the ‘community effort THING’ will be structured around one feature alone, the first section can be omitted.
Community Effort: TrueNAS CORE
= CHOOSING WHAT TO WORK ON =
The best place to start working on a task is to find something that
affects you personally (chances are other people will be affected by
the same thing).
If nothing affects you or you still cannot find anything try:
* Find some miss worded help messages or documents.
* Add some documentation you think will be helpful to others.
* Check bug reports
* Find security issues.
= SETTING UP A BUILD ENVIRONMENT =
* Source code for TrueNAS is located on Github at:
== REQUIREMENTS ==
1. Familiarity with the command line. If you are uncomfortable with the
command line you can find some reasonable instructions/help at the
following site:
https://lifehacker.com/a-command-line-primer-for-beginners-5633909
2. Git
To install Git on your system you can typically use a package
manger.
Ubuntu : `sudo apt install git`
Arch : `sudo pacman -S git`
FreeBSD : `sudo pgk install -y git`
=== CONFIGURE GIT ===
1. Setting authorship:
`git config --global user.name "Your name"`
`git config --global user.email "yourname@email.com"`
2. Enable a feature that will be useful when pushing code to a repository branch:
`git config --global push.autoSetupRemote true`
3. A login for GitHub.
4. Commit template
`git config --global commit.template <PATH/to>/.commit-template`
Save the following to `~/.commit-template`
```
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# You MUST wrap all lines at 72 characters.
#
# Commits should follow the following convention:
# * Subject: One line ONLY short meaningful description for logs
# * Blank Line: Follow the Subject with a blank line, do NOT remove
# * Details: Describe what changed and explain why it changed
# * Field: A description of why this change was made
#
# -------------------------------------------------------------------
# EX:
# xyz.file: Added the ABC option to foo()
#
# FEATURE: This will enable support for ABC.
#
# The `foo()` function, while supporting multiple options, did not
# include support for ABC.
#
# -------------------------------------------------------------------
# Fields:
# BUG: <bug number>
# FIXED-IN: <optional release version>
# FEATURE: <optional bug number>
# GUI:
```
5. Push Default
It is recommended to set the `push.default` to nothing:
`git config --global push.default nothing`
This option forces you to always enter the name of the remote branch
you wish to push to, rather than using a default value. This is good
practice as it ensures you push to the correct remote branch and avoid
accidentally pushing all local branches to the remote.
3. You will typically need two development environments. One for
`stable` and one for `development`. The environment for `stable`
(testing) should be a Virtual machine.
4. Unit testing
5. Coding standards
a. Comment all additions.
b. XXX: (fix now)
TODO: (fix when can)
6. Documentation standards
Looks like a good start.
A few points:
- FreeBSD does not install
sudoby default. Also, I’d imagine BSD folks like me generally preferdoasoversudo. The codebase is much simpler and cleaner and the config file syntax is also much cleaner and easier to understand. - You mistyped
pkgaspgk. - Is that 72 character restriction ixSystem’s convention? Seems kinda’ outdated for the modern times where 90% of monitors can easily display more than 72 characters without needing to wrap. Also, 72 is even lower than the 80 I’ve traditionally seen.
- Not sure about rule 2.
git pushwill NOT push all local branches just because you have them. The branch actually needs to have an actual remote branch attached for it to also push it there. ie. The remote has been set either bygit branch -u <upstream>or you once did agit push -u <origin> <branch>
Made up the 72 …well, actually copied and pasted from another older doc (more old school because of terminal usage).
Same with #2. I’ll have to remember what/where that came from. Okay to leave for now (not hurting anything)?
If you or anyone has any documentation standards, code comment standards, I would appreciate those.
I will update and edit the post above when I can.
I don’t post often (I lurk), but I had to chime in and clear this up because I feel you’re a valued contributor, @dan
iXsystems did not ‘buy’ FreeNAS. iX was asked to take over leadership of the FreeNAS project so that we could continue development and implement ZFS.
I’d prefer not to rehash the details from ages ago, but @Stux is right.
2 Likes
I was thinking about the documentation standards, the other day, and I think that if I spend a little time on a past side-project of mine it may be somewhat useful. At one time I needed an easier way to generate a man page and I really don’t know the mdoc format all that well so I wrote a quick markdown-to-mdoc converter. The utility I wrote wasn’t all that great (basically char substitution) but it would work well enough for simple markdown type documentation because man pages can be converted to a dozen or so different formats easy enough and the learning curve would be next to zero for any non-technical people that wanted to help.
I’ll have to dig up the utility and spend a bit of time porting it over because it uses pthreads (multi-threaded isn’t needed in an app like that but I was playing).
Dumb side-bar question: I assume ZFS development is still happening on SCALE (Linux), but just wanted to confirm those changes will/are being pushed back up to OpenZFS?
Shouldn’t it be the other way around, from OpenZFS to TN?
Yes, but iX has to make improvements so they’d push those changes back up the chain. EG: Microsoft will push changes they make to BSD code.
iX devs are one of the developers working on upstream OpenZFS.
Just check OpenZFS contributors for these devs:
amotin
ixhamza
usaleem-ix
And looks like they are pushing back changes from their soft fork upstream Sync truenas/zfs-2.3-release with upstream master by ixhamza · Pull Request #16055 · openzfs/zfs · GitHub
1 Like
Yes, we are a part of the OpenZFS Developer Community and always push improvements upstream.
1 Like
UPDATE: Last night, I found the utility and hacked up a few improvements to make it a bit friendlier. I only played with it for a few minutes so I’ll have to find more time in the very near future to get it to a point of general use. However, does this sound like something that could/would be used?
The following markdown writeup can be converted to mdoc (reminder mdoc can be converted to a number of different formats so that is why I pose the question). So, again, would it be a good idea to support simple documentation/writeups in this manner or would it be too constrained?
title: progname 7
author: John
# NAME
progname -- a program to change the world.
# SYNOPSIS
progname <inpputfile> <outputfile>
# DESCRIPTION
This utility will change the world because
it will remove all leading spaces from lines
in a text file.
# OPTIONS
-a
Append to the outout file.
-B
Use backward searching patterns (?...?).
-d
Parse `#defines` that don't take arguments.
-
# CODE EXAMPLE
<c
unsigned long str_version; /* version number */
unsigned long str_numstr; /* # of strings in the file */
unsigned long str_longlen; /* length of longest string */
>
# HISTORY
Created for personal use.
My program should now be portable and compiles cleanly.