This bug is intended to track any and all documentation changes that need to happen to successfully land OpenRC into Gentoo. It's also a meta bug for a migration guide that I would like to write with a member of the docs team. I've already shot an e-mail off to nightmorph about that.
softlevel= as a kernel parameter will be replaced by rc_runlevel= in OpenRC 0.2.2 and higher
(In reply to comment #1) > softlevel= as a kernel parameter will be replaced by rc_runlevel= in OpenRC > 0.2.2 and higher Will softlevel= still work until some version X (backward compatibility)?
of course
When I said "replaced", I meant in a documentation stand point that we should be promoting this as a the default parameter to set. I'm just trying to keep notes on this bug rather then in my head or on a piece of paper or a file that only I can access. That way, if I miss something.. or I get something wrong.. someone else can contribute.
We only mention softlevel in two documents: http://www.gentoo.org/doc/en/power-management-guide.xml, which has two related open bugs already (bug #205117 and bug #209258) -- this definitely needs some fixes, which no one's coherently provided thus far. http://www.gentoo.org/doc/en/handbook/hb-working-rcscripts.xml Please look through these docs and figure out what needs to be changed to what. Our documentation will *not* be split into "stable baselayout-1" and "~arch openrc" bits. I'd prefer to just default all instructions to OpenRC once it's stable, since it doesn't look like baselayout-1 will be maintained after that point. All that being said, we're closer to fixing this tracker bug, as the openrc migration guide is complete.
The documentation net.example in particular needs to be updated. Apparently comments inside /etc/conf.d/net commands foul them up. Example: pppd_ppp0=" # maxfail 0 # WARNING: It's not recommended you use this # # if you don't specify maxfail then we assume 0 # updetach # If not set, "/etc/init.d/net.ppp0 start" will return " "/etc/init.d/net.ppp0 start" will cause it to not parse properly. Also could you add documentation on what the syntax is for setting up two phone numbers for dial up? #phone_number_ppp0="12345689" # Maximum 2 phone numbers are supported Used to be: phone_number_ppp0=( "12345689 "12345678") Is it now this? phone_number_ppp0="'12345689' '12345678'" or? phone_number_ppp0="12345689 12345678"
Sorry old style syntax was this: phone_number_ppp0=( "12345689" "12345678" )
(In reply to comment #6) > The documentation net.example in particular needs to be updated. (This is a tracker so being brief.) Note that the network config is still in flux. As the current GMN announcement states, this is ~arch for a reason. GMANE link to discussion thread with the details: http://thread.gmane.org/gmane.linux.gentoo.devel/55824
Does anyone know where I can find the (official) developer docs for openrc. I'm trying to find out the purpose of all the directories in /lib/rc/init.d. I'm not sure about things such as "exclusive", "scheduled", etc.
Not the bug for this..
May be bug 240984 could became addition here. At least part on "The cold/hotplugging has now been moved into one variable - rc_hotplug"
*** Bug 246119 has been marked as a duplicate of this bug. ***
*** Bug 260761 has been marked as a duplicate of this bug. ***
*** Bug 266785 has been marked as a duplicate of this bug. ***
Not sure wether this is the right place for this (otherwise please point me to the right place). I noticed in the gentoo handbook, the page on configuring your system (http://www.gentoo.org/doc/en/handbook/handbook-amd64.xml?part=1&chap=8) still mentions that rc.conf has the EDITOR and DISPLAYMANAGER variables. Also, the migration guide mentions to set the EDITOR variable in /etc/env.d while the comments in /etc/profile suggest setting a system default for this in /etc/profile.d.
Can we have an update on this bug? Is it here to trackthe work on the migration guide only, or what else is supposed to be tracked here? Thanks, William
Docs team, I need status please? Is this bug resolved? Thanks, William
As far as I know we keep this bug open so that as new config issues come up we can handle them quickly. As OpenRC upstream doesn't seem to have a set config syntax, it changes often enough either on the upstream side or the Gentoo side that the doc needs updates fairly often. More to the point, we keep this bug open because when/if OpenRC and baselayout-2 go stable, we'll need to apply all the changes in this bug to the rest of our documentation. Right now only the migration guide has anything -- every single other doc is setup for baselayout-1 and the "usual" initscripts.
(In reply to comment #18) > As far as I know we keep this bug open so that as new config issues come up we > can handle them quickly. As OpenRC upstream doesn't seem to have a set config > syntax, it changes often enough either on the upstream side or the Gentoo side > that the doc needs updates fairly often. > More to the point, we keep this bug open because when/if OpenRC and > baselayout-2 go stable, we'll need to apply all the changes in this bug to the > rest of our documentation. Right now only the migration guide has anything -- > every single other doc is setup for baselayout-1 and the "usual" initscripts. In that case, shouldn't the stabilization tracker block this bug instead of the other way around like it is now? Thanks, William
(In reply to comment #19) > In that case, shouldn't the stabilization tracker block this bug instead of the > other way around like it is now? I'd rather not. Converting all our documentation to use OpenRC/baselayout-2 is a massive undertaking -- I'd like to have it done immediately prior to stabilization, or at the same time. We need time to get it all documented. It should be a simultaneous stabilization/doc effort by the package maintainers and the GDP, otherwise our users will be very, very unhappy.
The documentation is going to depend if we stay with the current /etc/conf.d/net with /etc/init.d/net.bla or go with the new /etc/conf.d/network
(In reply to comment #21) > The documentation is going to depend if we stay with the current > /etc/conf.d/net with /etc/init.d/net.bla or go with the new /etc/conf.d/network I'm not sure this has to be a one or the other situation. We will need to document the new network scriptss and tell users how to switch over to them if they want to, but for now at least, we are supporting both afaik.
i dont think anything is changing with /etc/init.d/net* stuff. the default is still /etc/init.d/net.${iface} like it always has been. since Roy is no longer driving things, i suggest we quietly mothball /etc/init.d/network and forget about the "old" vs "new" net stuff.
*bump* this seems to be the only bug blocking bug #295613 Is the doc team on the cc list here? Closing this bug would have a nice domino affect
(In reply to comment #24) > Is the doc team on the cc list here? Closing this bug would have a nice domino > affect The docs team is the assignee of the bug. :) Problem is, someone has to do the work to be able to close this bug.
This is a tracker bug, so it stays open until all our docs have been migrated to OpenRC/baselayout-2, which won't be happening until they go stable on all arches, and are present in our installation media. In the future, please send inqueries of this nature via IRC or email lists, rather than adding comments to the bug. Thanks.
(In reply to comment #26) > This is a tracker bug, so it stays open until all our docs have been migrated > to OpenRC/baselayout-2, which won't be happening until they go stable on all > arches, and are present in our installation media. Isn't that a chicken and egg problem? If you document it, it can go stable faster. Also, you would have saved both Mike and me bug #346783 altogether. What's the problem with a note on ~arch and OpenRC?
(In reply to comment #27) > Also, you would have saved both Mike and me bug #346783 altogether. Please read the OpenRC migration guide; it already covers kernel module configuration. > What's the problem with a note on ~arch and OpenRC? We will not document ~arch packages in our handbook. That is our policy, and it is not going to change. If you want to know why we won't fork our documentation, please read all the similar threads on the gentoo-doc mailing list, and even check the forums for posts by myself and other GDP members. Your question has already been answered -- it comes up every now and then, and our response has not changed. No one has said a word to the GDP in recent months about any realistic plan or schedule for stabilizing OpenRC/baselayout-2 across all arches. Until then, the only place we'll document those packages is in the migration guide. Again, please refrain from posting unnecessary comments. This bug is for monitoring individual documents that need updating. Anything else just adds more spam to everyone's inboxes, and make it harder to keep track of actual problems for the GDP to fix.
Removing a non-blocking bug per its comment 17. Nothing the GDP can take care of.
I'm working on some parts of this now.
*** Bug 366603 has been marked as a duplicate of this bug. ***
I had a lot of trouble figuring out how to make a static route work out until I happened on one little clue. The advice given in Code Listing 2.11 ought to work, but it didn't. It turns out that, contrary to some of the old comments--including the openrc-0.8.2-r1/README.newnet.bz2 file--I do not need to set up /etc/conf.d/staticroute. Code Listing 2.11 indicates that the new style for /etc/conf.d/net should have config_eth0="192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255" When I did things this way, I kept getting an SIOCADDRT error message about a process not being found. When I changed things to the form shown in openrc-0.8.2-r1/net.example, my static route worked great. The key is to omit the broadcast address. I also changed things to the CIDR form, as the example shows: config_eth0="192.168.1.37/27" I had no trouble with the routes_eth0 line.
*** Bug 368169 has been marked as a duplicate of this bug. ***
Hi, I'm following this bug because i've noticed some weird things in the installation process (gentoo handbook) It seems that latest stage3 tarball (stage3_amd64_20110520) mix baselayout1 and baselayout2. For example : Doc stat that : modify /etc/conf.d/clock but in this stage tarball the right file is /etc/conf.d/hwclock. But at the same time, /etc/conf.d/net is still the right file for configuring network Same for timezone (/etc/timezone ????). Complaining here because it's really confusing for new user to follow things clearly. (i'm installing gentoo since many years so it's not really a problem for me, but i always recommend Gentoo to my friends and a lot of them complaining about diffculties to achieve installation, cause of this openRC migration) Gentoo handbook say this : Stage3 tarballs can be downloaded from releases/amd64/autobuilds/current-stage3/ on any of the Official Gentoo Mirrors and are not provided on the LiveCD. And i think this is THE sentence confusing everyone. Maybe you should just build a baselayout1 final tarball and point to it in the handbook. So you can wait for OpenRC migration to complete. I hope you understand that this minor bug can be a critical bug for community Best regards,
*** Bug 368793 has been marked as a duplicate of this bug. ***
*** Bug 369013 has been marked as a duplicate of this bug. ***
(In reply to comment #34) > Hi, > I'm following this bug because i've noticed some weird things in the > installation process (gentoo handbook) [...] > Doc stat that : modify /etc/conf.d/clock but in this stage tarball the right > file is /etc/conf.d/hwclock. But at the same time, /etc/conf.d/net is still > the right file for configuring network > > Same for timezone (/etc/timezone ????). [...] Same issues are in the Localization Guide.
*** Bug 369367 has been marked as a duplicate of this bug. ***
*** Bug 369935 has been marked as a duplicate of this bug. ***
*** Bug 370955 has been marked as a duplicate of this bug. ***
*** Bug 372219 has been marked as a duplicate of this bug. ***
The item I would like to add is simply an ordering-swap: In both the cases of the x86 and amd64 documentation, creation of the network device(s) must be performed BEFORE adding the device(s) to the default runlevel. As it is currently in the manual, the steps are inverted. The latest stage tarballs of both x86 and amd64 do NOT contain an net.eth0 nor an net.wlan0 or other except for net.lo (which is correct). Please refer to the relevant portion of the (amd64) manual: http://www.gentoo.org/doc/en/handbook/handbook-amd64.xml?part=1&chap=8#doc_chap2 Basically, Code Listing 2.9: Creating [extra] initscripts should come before Code Listing 2.8: Adding net.eth0 to the default runlevel Perhaps a line prefacing the two explaining that the user must choose the network devices that will be used by the system. Thank you.
*** Bug 373597 has been marked as a duplicate of this bug. ***
*** Bug 373593 has been marked as a duplicate of this bug. ***
Not sure if it's the right place but x86 handbook still refers to old style modules autoloading: http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&chap=7 This should be updated with using /etc/conf.d/modules
Also clock setup located at http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&chap=8 should be updated with using /etc/conf.d/hwclock
btw, the module stuff fix is part of bug #369841
*** Bug 374773 has been marked as a duplicate of this bug. ***
*** Bug 374993 has been marked as a duplicate of this bug. ***
*** Bug 377309 has been marked as a duplicate of this bug. ***
Created attachment 286007 [details, diff] Patch to update gentoo-freebsd This patch updates the old path in the guide. I'm working on patching some other docs too.
Created attachment 286009 [details, diff] Fixed doc discarding the timezone variable
Created attachment 286015 [details, diff] Fix the handbook so it properly refers to the clock variable and discards the TIMEZONE=" There is an issue in the handbook using old variables and adding a TIMEZONE=" in /etc/timezone which shouldn't be there.
*** Bug 382525 has been marked as a duplicate of this bug. ***
Please add "Changelog" file to openrc-xxx.tar.bz
Nikolay: what do you mean with adding ChangeLog to openrc-xxx.tar.bz2? You mean that the tarball (sources) of OpenRC should contain a ChangeLog file? If so, then please create a separate bug report on that, this tracker is for documentation changes.
No open issues. Please report any findings as new bugs.
