Documentation Seriously Out of Date

[Dennis Jensen]

I was searching through the 9.10 Documentation to see if I can find out how the New Build Topology is laid out so that I can find out what happened to several of the 9.3 files that no longer exists in 9.10 namely (Makefile, build/nanobsd/nanobsd_funcs.sh, src/freenas-pgktools/lib/configuration.py, and src/freenas-pgktools/lib/__init__.py) and I came across some documentation that is extremely out of date.

docs/howtos/using-rst.rst
This one references FreeNAS 8.x and this is FreeNAS 9.10 documentation ?? The file itself may not need to be updated since it only talks about how to implement RST but references to outdate versions should at least be removed to reduce confusion.

docs/process/releng.rst
This documentation talks about moving FreeNAS to Git sometime in the future which is obviously where it is now so not sure exactly sure how out of date this document is.

docs/specs/build/design.rst
This documentation talks about how NanoBSD is an integral part of the build system which as of about 9.3 was virtually non-existent and now in 9.10 I believe completely non-existent

docs/specs/installation/design.rst
This appears to be the companion document to the previous document and it too mentions Nanobsd so it is probably as out of date as its companion

Not sure if any of the other documents in this directory are up to date or not but I have to ask why include documentation like this if it is no longer applicable -- I mean no documentation (while not a good thing) is a whole lot more preferred then bad documentation as that is simply a waste of time and could be extremely confusing for the unknowing.

By the way -- Is there any documentation that outlines how the New Build System works and where various files (or their contents) that were in 9.3 ended up in the 9.10 Release. I have been researching this but I have yet to find anything that helps me understand how to implement my changes back into FreeNAS when going from FreeNAS 9.3 to FreeNAS 9.10 since some of my changes were contained within the old build system that no longer exists.

Note: I know that there is a Makefile in the FreeNAS-Build and a Makefile.inc1 that seem to cover much of what was in the original Makefile in 9.3 but there are elements of the original Makefile that are not within these 2 files and I am wondering if they were put somewhere else (such as the UPDATE_HOST?= variable in the old Makefile)

Thanks in advance.

 

[anodos]

I was searching through the 9.10 Documentation to see if I can find out how the New Build Topology is laid out so that I can find out what happened to several of the 9.3 files that no longer exists in 9.10 namely (Makefile, build/nanobsd/nanobsd_funcs.sh, src/freenas-pgktools/lib/configuration.py, and src/freenas-pgktools/lib/__init__.py) and I came across some documentation that is extremely out of date.

docs/howtos/using-rst.rst
This one references FreeNAS 8.x and this is FreeNAS 9.10 documentation ?? The file itself may not need to be updated since it only talks about how to implement RST but references to outdate versions should at least be removed to reduce confusion.

docs/process/releng.rst
This documentation talks about moving FreeNAS to Git sometime in the future which is obviously where it is now so not sure exactly sure how out of date this document is.

docs/specs/build/design.rst
This documentation talks about how NanoBSD is an integral part of the build system which as of about 9.3 was virtually non-existent and now in 9.10 I believe completely non-existent

docs/specs/installation/design.rst
This appears to be the companion document to the previous document and it too mentions Nanobsd so it is probably as out of date as its companion

Not sure if any of the other documents in this directory are up to date or not but I have to ask why include documentation like this if it is no longer applicable -- I mean no documentation (while not a good thing) is a whole lot more preferred then bad documentation as that is simply a waste of time and could be extremely confusing for the unknowing.

By the way -- Is there any documentation that outlines how the New Build System works and where various files (or their contents) that were in 9.3 ended up in the 9.10 Release. I have been researching this but I have yet to find anything that helps me understand how to implement my changes back into FreeNAS when going from FreeNAS 9.3 to FreeNAS 9.10 since some of my changes were contained within the old build system that no longer exists.

Note: I know that there is a Makefile in the FreeNAS-Build and a Makefile.inc1 that seem to cover much of what was in the original Makefile in 9.3 but there are elements of the original Makefile that are not within these 2 files and I am wondering if they were put somewhere else (such as the UPDATE_HOST?= variable in the old Makefile)

Thanks in advance.

https://github.com/freenas/freenas/commit/aa1e02879dd4a1c8a8e264af1b52c154707006c8

Looks like those old docs got nuked 12 days ago. So... I guess that's the direction things are going.

The real FreeNAS 9.10 documentation is housed here: http://doc.freenas.org/9.10/freenas.html

 

[dlavigne]

Note that docs now have their own repo: https://github.com/freenas/freenas-docs. This is to make it easier to know you are looking at the right doc src as you had to know which branch was currently being used in the old freenas doc repo (now you just look at the files that are there as docs always use the master branch).

 

[Dennis Jensen]

Well that is great to hear -- sorry if I am not on top of the latest releases as I am trying to move our system from FreeNAS 9.3 to FreeNAS 9.10 and I needed to halt progression on 9.10 until this has been completed. Once I have moved our stuff form FreeNAS 9.3 to FreeNAS 9.10 I can work on moving from current state of FreeNAS 9.10 to whatever happens to be the most current Stable state of 9.10

Thanks for the heads up on that documentation though.

I looked at that repo you suggested to go to and that is the same or very close to the same documentation that I have in my FreeNAS 9.10 and is horribly out of date but thanks anyway I am guessing that eventually it will be updated.

 

[dlavigne]

Also note that doc.freenas.org/9.10 is synced with latest doc src whenever a new update is pushed. So the only time you should see a difference between the two is in the intervening hours/days when the doc team has finished their edits for the next update and when the next update is actually released.

 

[Dennis Jensen]

Okay as I amended my previous reply -- the docs in https://github.com/freenas/freenas-docs are the ones I have (or at least seem to be) and are thus horribly out of date.

Further I do not see anywhere that they talk about how the New Build System in 9.10 works in comparison to how the Build System worked in 9.3 the closest thing I have thus far is: https://bugs.pcbsd.org/issues/9041

This gives at least an overview of what was and what might be -- and going through the actually commits associated with this was somewhat helpful but there are still a lot of unknowns about how the New Build System is meant to work and how to map the 9.3 Build System to the new 9.10 build system so one can update their changes to current version of FreeNAS

 

[dlavigne]

There shouldn't be any docs at all about the build system in the new doc repo (just how to build docs). What is the exact URL to the src file you think is out of date in the doc repo?

The FreeNAS build system README would be for the branch you want to build at freenas/freenas (eg every branch has its own README), and it is very possible that the 9.10 branch is out of date as the dev team has been changing the build system the past few weeks. In that case, you would want to make a bug report at bugs.freenas.org so a dev can update the build README.

 

[Dennis Jensen]

https://github.com/freenas/freenas-docs/blob/master/specs/build/design.rst

 

[dlavigne]

Thanks for clarifying! Anything outside of "userguide" is a dev team thing and would need a bug report at bugs.freenas.org. Anything within "userguide" is a doc team thing and can either go through me, the forums, or a doc bug report

I'm pretty sure those extra folders (eg howtos, process, specs, etc.) are a bug (as in should not be there), but the dev team would need to make a decision on that.

 

[Dennis Jensen]

Ah okay

As for that README are you talking about the README.md that is within the Repository that I cloned or a different README file located somewhere else ??

If the former that just covers how to to do a build -- not how the new build system works -- we have already created a Vanilla FreeNAS 9.10 but that does not help us with re-injecting our code changes into FreeNAS 9.10 as the files that used to contain some of the code are no longer present and for that matter it is hard to tell if our old changes will be handled the same way within this new build system. Just trying to figure out how this new build system works compared to the old build system.

If you are talking about a different README file can you toss me a bone and provide the URL to it?

 

[dlavigne]

Let's see if I can be clear (which is hard when you're dealing with multiple branches over multiple repos)...

https://github.com/freenas/freenas-docs/blob/master/README.md explains how to build the User Guide. When it was put there, the userguide was the only thing in that repo. Since then, devs have put other stuff there andthen taken some of there stuff away (last I had heard until today they had deleted all their stuff so at some point it was put back). If, after your bug ticket, the devs don't remove the other dirs, I will move that README to https://github.com/freenas/freenas-docs/tree/master/userguide to make it even clearer that it only applies to the user guide. Though, when I see your ticket go by, I will comment that this repo was just supposed to be for the user guide...

https://github.com/freenas/freenas/blob/9.10-STABLE/README.md has the instructions for building 9.10. If it does not work, a bug needs to be created at bugs.freenas.org so a dev can update it.

https://github.com/freenas/freenas/blob/9.3-STABLE/README.md has the instructions for building 9.3. If it does not work, a bug needs to be created at bugs.freenas.org so a dev can update it.

Is that clearer?

 

[Dennis Jensen]

Thanks for the clarification.

As for those 2 README.MD files *sigh* I do not need to know how to "build" a vanilla 9.10 or how to "build" vanilla 9.3 we have that done. What I am trying to figure out is how these 2 definitely different topologies actually differ. I mean we have code in the 9.3 Build Topology and we pretty much kind of understood how it worked -- however 9.10 introduces a totally different Topology and even deletes major chunks of the older system while also ripping it out of the main system and putting into its own repository -- This makes mapping the actually changes a horrendous nightmare since there does not seem to be a clear roadmap of how they went form old A to new Z -- Oh and please do not get me wrong, I love the idea and I applaud the concept (from what I understand of it) but that does not help me figure out how to move my code changes in 9.3 Build System into the new 9.10 Build System since the new build system uses this totally new and revolutionary concept which does not seem to be documented anywhere -- again I think (from what I understand) this new topology is a very good idea

 

[dlavigne]

Do you mean 10 or 9.10? 10 is an entirely different beast which is still in alpha stage, whereas 9.10 is a continuation of the 9.3 UI on a 10 kernel (ie no UI changes).

If you really do mean 9.3 -> 9.10, you can read the history of all user-facing changes at:

https://github.com/freenas/freenas/commits/9.10-STABLE?author=dlavigne

and for those that will be in the next software update (these doc changes happened in new repo):

https://github.com/freenas/freenas-docs/commits/master

 

[Dennis Jensen]

First yes I mean going from FreeNAS 9.3 to FreeNAS 9.10 and the "build" system has already been overhauled in FreeNAS 9.10 and moved to its own repository FreeNAS-Build.git along with this move to the new repository the new build topology was implemented which got rid of all the remaining Nano files as well as a few other files that existed in the FreeNAS 9.3 build system.

I will look at these "user-facing" changes and see if they outline at all how the inner workings changed since that is more of what I am looking to understand. It is kind of like making modifications to an engine and then not only did they move the engine from the front to the back of the car they changed the engine from being carburetor gas powered to being fuel-injected hybrid... yeah some of it looks the same and kind of works the same but not entirely and its kind of hard to tell where we are supposed to attached our hardware and/or if that hardware is even needed anymore and what new hardware might be needed.

 

[dlavigne]

From an end-user point of view it should be as the doc team carefully tracks and records each user-facing change for every software update.

As for how the build has changed, that's a dev question

 

[dlavigne]

Notes that the whole reason this sub-forum was created (the FAQ thread) has been deleted and moved to the wiki. Accordingly, I'm going to move this thread somewhere else and nuke this sub-forum.

 

[Dennis Jensen]

Okay thanks for saving me time on that one :) btw can you point me in the direction of how to create a bug ticket I have not done that as of yet Also which forum area should I go to post that build change question so that the right folks might answer it ?

 

[Dennis Jensen]

Okay but do let me know where you move this too so I can be sure to address these kind of questions to the appropriate place in the future

 

[dlavigne]

You should get a notification, but it's in Help & Support -> Bug Reporting Discussion.

 

[dlavigne]

http://doc.freenas.org/9.10/freenas_system.html#support (or, just skip that screen and do the same thing at bugs.freenas.org).