PR#48: format - fesco/fesco-docs

fesco / fesco-docs

#48 format

Merged 2 years ago by zbyszek. Opened 2 years ago by jibecfed.

fesco/ jibecfed/fesco-docs format into master

format

Jean-Baptiste Holcroft • 2 years ago

9a63ddb

fesco/modules/ROOT/pages/FESCo_election_policy.adoc

file modified

+67 -67

		`@@ -9,78 +9,78 @@`
		`== Digest`

		`* FESCo elections will be held twice a year,`
		`- as part of the Fedora Project combined election process.`
		`+ as part of the Fedora Project combined election process.`

		`* There will be 9 seats on FESCo.`

		`* 9 seats will be up for the F9 elections,`
		`- the F10 election will have 4 seats up for vote.`
		`- The 4 seats that will be up for election`
		`- will be the bottom 4 vote-getters`
		`- from the prior election.`
		`- The 5 seats not up for election in the F10 election,`
		`- will be up for election in F11.`
		`- After that,`
		`- the seats up for election will alternate`
		`- based on the seats up for election`
		`- in the prior election.`
		`+ the F10 election will have 4 seats up for vote.`
		`+ The 4 seats that will be up for election`
		`+ will be the bottom 4 vote-getters`
		`+ from the prior election.`
		`+ The 5 seats not up for election in the F10 election,`
		`+ will be up for election in F11.`
		`+ After that,`
		`+ the seats up for election will alternate`
		`+ based on the seats up for election`
		`+ in the prior election.`

		`* The elections will be announced in public lists.`
		`- A reminder mail to eligible voters`
		`- will be sent three days before the close of the election.`
		`+ A reminder mail to eligible voters`
		`+ will be sent three days before the close of the election.`

		`* Candidates may be any member of the packager group`
		`- in the Fedora Accounts System.`
		`+ in the Fedora Accounts System.`

		`* Candidates must self-nominate`
		`- at least three days before the election opens`
		`- by writing their information onto the wiki.`
		`+ at least three days before the election opens`
		`+ by writing their information onto the wiki.`

		`* A minimum number of candidates are necessary`
		`- in order to hold an election.`
		`- This will be the number of open seats + 25%.`
		`+ in order to hold an election.`
		`+ This will be the number of open seats + 25%.`

		`* If not enough candidates have signed up by the deadline,`
		`- the election may be delayed`
		`- waiting for more candidates to appear,`
		`- in coordination with the schedule for combined Fedora elections.`
		`- If there are still not enough candidates,`
		`- the candidates who are present will be voted upon`
		`- (or merely confirmed if there are less candidates than open seats.)`
		`+ the election may be delayed`
		`+ waiting for more candidates to appear,`
		`+ in coordination with the schedule for combined Fedora elections.`
		`+ If there are still not enough candidates,`
		`+ the candidates who are present will be voted upon`
		`+ (or merely confirmed if there are less candidates than open seats.)`

		`* If there are not enough candidates to complete the ballot,`
		`- all the contributors listed in this section`
		`- will be added to the ballot.`
		`+ all the contributors listed in this section`
		`+ will be added to the ballot.`

		`* If FESCo does not have the full number of seats filled at this point,`
		`- the vacant seats will attempted to be filled by the following methods:`
		`+ the vacant seats will attempted to be filled by the following methods:`

		`. If there are runner-up candidates from the previous election`
		`- that did not have the opportunity to be on FESCo,`
		`- they will be offered a seat`
		`- according to their rank in the voting.`
		`+ that did not have the opportunity to be on FESCo,`
		`+ they will be offered a seat`
		`+ according to their rank in the voting.`

		`. If those candidates have been exhausted,`
		`- FESCo will ask Fedora community members`
		`- that they think would do a good job`
		`- if they would be willing to hold the open seats.`
		`+ FESCo will ask Fedora community members`
		`+ that they think would do a good job`
		`+ if they would be willing to hold the open seats.`

		`. If the open seats are still not filled,`
		`- FESCo will operate with less members`
		`- until the next FESCo election.`
		`+ FESCo will operate with less members`
		`+ until the next FESCo election.`

		`The voting is as follows:`

		`* A voter receives a ballot`
		`- listing all the candidates.`
		`+ listing all the candidates.`

		`* For each candidate`
		`- the voter assigns from 0 to number of candidates points.`
		`+ the voter assigns from 0 to number of candidates points.`

		`* At the close of the election,`
		`- the points for each candidate are tallied`
		`- and the ones with the most points`
		`- win a seat.`
		`+ the points for each candidate are tallied`
		`+ and the ones with the most points`
		`+ win a seat.`

		`There are no term limits imposed by this policy.`
		`If FESCo chooses to impose term limits`
		`@@ -178,31 +178,31 @@`
		`by the following methods:`

		`* If the remaining duration of the vacated seat's term`
		`- is less than a full Fedora release cycle,`
		`- a replacement should be appointed`
		`- by the remaining members of FESCo`
		`- by full consensus.`
		`- If no consensus can be reached by FESCo,`
		`- the Fedora Council will be asked to select`
		`- from the available candidates`
		`- through whatever mechanism they see fit.`
		`+ is less than a full Fedora release cycle,`
		`+ a replacement should be appointed`
		`+ by the remaining members of FESCo`
		`+ by full consensus.`
		`+ If no consensus can be reached by FESCo,`
		`+ the Fedora Council will be asked to select`
		`+ from the available candidates`
		`+ through whatever mechanism they see fit.`

		`* If the remaining duration of the vacated seat's term`
		`- is more than a full release cycle,`
		`- then a candidate will be appointed`
		`- as for the above case`
		`- until the next election cycle begins.`
		`- During this election cycle,`
		`- the normal election seats will be filled first`
		`- by the candidates with the most votes.`
		`- After those seats are filled,`
		`- any vacated seats will be filled`
		`- by the candidates with the next-highest number of votes.`
		`+ is more than a full release cycle,`
		`+ then a candidate will be appointed`
		`+ as for the above case`
		`+ until the next election cycle begins.`
		`+ During this election cycle,`
		`+ the normal election seats will be filled first`
		`+ by the candidates with the most votes.`
		`+ After those seats are filled,`
		`+ any vacated seats will be filled`
		`+ by the candidates with the next-highest number of votes.`

		`* Vacated seats filled outside of the normal two-release cycle`
		`- will serve for only a single Fedora release cycle`
		`- so that their seats are back on schedule`
		`- for the following term.`
		`+ will serve for only a single Fedora release cycle`
		`+ so that their seats are back on schedule`
		`+ for the following term.`

		`[[voting_system]]`
		`== Voting System`
		`@@ -246,14 +246,14 @@`
		`* Web based administration to create a new election.`

		`* Creation of a new election`
		`- needs to trigger generation of a script`
		`- that will interact with the accounts db and election db`
		`- to send out a reminder to vote message`
		`- three days before the close of the election.`
		`+ needs to trigger generation of a script`
		`+ that will interact with the accounts db and election db`
		`+ to send out a reminder to vote message`
		`+ three days before the close of the election.`

		`* The interface will show the voter ballots`
		`- for all the elections`
		`- that they can vote in.`
		`+ for all the elections`
		`+ that they can vote in.`

		`Other enhancements:`

fesco/modules/ROOT/pages/Fails_to_build_from_source_Fails_to_install.adoc

file modified

+1 -1

		`@@ -165,7 +165,7 @@`
		`released.`

		`* If the build of your package fails due to a bug in another package`
		`- (such as a compiler bug or missing dependency):`
		`+ (such as a compiler bug or missing dependency):`

		`. Find an existing bug for that package describing the problem. Set`
		`your bug to "Depends on" that other bug. Do not change the component of`

fesco/modules/ROOT/pages/Policy_for_encouraging_comaintainers_of_packages.adoc

file modified

+101 -108

		`@@ -32,19 +32,18 @@`
		`The most important reasons for this rule are:`

		`* One maintainer can commit fixes`
		`- like patches or new upstream releases that fix important bugs`
		`- (for example security data-corruption issues`
		`- or packaging bugs that confuse the users' systems)`
		`- even when the other maintainer(s) are away from the keyboard`
		`- due to traveling, sleeping or whatever.`
		`+ like patches or new upstream releases that fix important bugs`
		`+ (for example security data-corruption issues`
		`+ or packaging bugs that confuse the users' systems)`
		`+ even when the other maintainer(s) are away from the keyboard`
		`+ due to traveling, sleeping or whatever.`

		`* Maintainers further can help, guide and watch each other,`
		`- which should lead to better overall package quality.`
		`+ which should lead to better overall package quality.`

		`The goal is to have at least three maintainers per package`
		`and at least two per supported distribution release.`
		`- Big and important packages should have more maintainers`
		`- -- there is no upper limit.`
		`+ Big and important packages should have more maintainers -- there is no upper limit.`

		`There is a primary maintainer who takes care of the package in general.`
		`It is their job to approve and find new maintainers`
		`@@ -63,15 +62,13 @@`
		`and also try to get a second one.`
		`That means asking on the mailing list now and then`
		`for people that might be interested in the job.`
		`- The goal is to have that process mostly automated`
		`- -- e.g. let a script parse the owner information now and then`
		`+ The goal is to have that process mostly automated -- e.g. let a script parse the owner information now and then`
		`and send out the list of the packages`
		`that do not have enough co-maintainers yet`
		`to a mailing list.`

		`The primary maintainer can't block co-maintainers for a distribution`
		`- only because they do not want to support that distribution`
		`- -- e.g. if they do not want to care about their package in EPEL,`
		`+ only because they do not want to support that distribution -- e.g. if they do not want to care about their package in EPEL,`
		`they have to accept somebody else takes care of the package in EPEL.`

		`== Guidelines`
		`@@ -94,104 +91,104 @@`
		`Something like the following points describe the concept roughly:`

		`* In most cases the primary maintainer`
		`- is the primary per-release maintainer`
		`- for all supported distributions.`
		`- There are two co-maintainers.`
		`- The three make sure everybody knows the important stuff`
		`- and they share the load,`
		`- to make sure everybody knows about the details of the package.`
		`+ is the primary per-release maintainer`
		`+ for all supported distributions.`
		`+ There are two co-maintainers.`
		`+ The three make sure everybody knows the important stuff`
		`+ and they share the load,`
		`+ to make sure everybody knows about the details of the package.`

		`* The primary maintainer should normally be`
		`- the primary per-release maintainer for the Fedora devel branch,`
		`- as that is the most important one.`
		`+ the primary per-release maintainer for the Fedora devel branch,`
		`+ as that is the most important one.`

		`* All maintainers of a particular package`
		`- should be co-maintainers or observers`
		`- (somebody that gets CCed to bugs`
		`- and get noticed of commits and builds,`
		`- but normally doesn't do any work)`
		`- for the Fedora devel branch,`
		`- as that's where all the fun stuff happens.`
		`+ should be co-maintainers or observers`
		`+ (somebody that gets CCed to bugs`
		`+ and get noticed of commits and builds,`
		`+ but normally doesn't do any work)`
		`+ for the Fedora devel branch,`
		`+ as that's where all the fun stuff happens.`

		`* The per-release primary maintainer`
		`- takes care of the a package for that release.`
		`- They should have at least one co-maintainer`
		`- for maintaining that package in that release.`
		`+ takes care of the a package for that release.`
		`+ They should have at least one co-maintainer`
		`+ for maintaining that package in that release.`

		`* Bugs get assigned to the primary per-release maintainer.`
		`- The primary maintainer and the co-maintainer for that release`
		`- get into the CC list.`
		`- The per-release maintainer has to make sure the bugs get fixed,`
		`- but of course some of the other maintainers of that package can do that, too.`
		`+ The primary maintainer and the co-maintainer for that release`
		`+ get into the CC list.`
		`+ The per-release maintainer has to make sure the bugs get fixed,`
		`+ but of course some of the other maintainers of that package can do that, too.`

		`* All maintainers should check each others commits for correctness and sanity.`

		`* The primary maintainer should make sure that`
		`- important bugfixes get applied`
		`- to all the supported distributions`
		`- as needed.`
		`+ important bugfixes get applied`
		`+ to all the supported distributions`
		`+ as needed.`

		`* For the devel branch:`
		`** Small changes`
		`- (for example: package enhancements, bugfixes)`
		`- and medium sized changes`
		`- (for example: update from 1.0.1 to 1.0.2)`
		`- go directly to cvs and get built.`
		`- If someone feels unsure about a commit`
		`- they should wait one or two days`
		`- before actually building`
		`- or pushing the package out to the repos,`
		`- as that should give the other maintainers a chance`
		`- to yell if they see problems.`
		`+ (for example: package enhancements, bugfixes)`
		`+ and medium sized changes`
		`+ (for example: update from 1.0.1 to 1.0.2)`
		`+ go directly to cvs and get built.`
		`+ If someone feels unsure about a commit`
		`+ they should wait one or two days`
		`+ before actually building`
		`+ or pushing the package out to the repos,`
		`+ as that should give the other maintainers a chance`
		`+ to yell if they see problems.`
		`** Big changes`
		`- (for example:`
		`- update from 1.0.1 to 1.2.0`
		`- or heavy changes in the spec file)`
		`- should normally get coordinated between the different maintainers;`
		`- a temporary separate branch in the cvs, e-mail or bugzilla`
		`- can be used for this purpose.`
		`+ (for example:`
		`+ update from 1.0.1 to 1.2.0`
		`+ or heavy changes in the spec file)`
		`+ should normally get coordinated between the different maintainers;`
		`+ a temporary separate branch in the cvs, e-mail or bugzilla`
		`+ can be used for this purpose.`

		`* For released distributions:`
		`- Small changes`
		`- (for example: package enhancements, bugfixes)`
		`- get go directly to cvs.`
		`- The other maintainers of that package`
		`- should have the chance`
		`- (e.g. a short time period, like two days)`
		`- where they can commit other enhancements`
		`- (to save users lots of upgrades)`
		`- or to discuss the committed change`
		`- before its actually pushed to the users.`
		`- With the current (FC7T1) scheme it means:`
		`- don't build the package immediately.`
		`- (In the future with the new repo push stuff from lmacken`
		`- it hopefully should be easily possible`
		`- to define a waiting period in updates-testing`
		`- before a package gets pushed out to the proper repo.)`
		`- Only the per-distribution maintainer`
		`- should commit and build medium sized changes.`
		`- Those should be tested in devel first`
		`- and co-maintainers should have a chance`
		`- to comment on the commits`
		`- before the package gets in the repo.`
		`- Big changes get coordinated.`
		`+ Small changes`
		`+ (for example: package enhancements, bugfixes)`
		`+ get go directly to cvs.`
		`+ The other maintainers of that package`
		`+ should have the chance`
		`+ (e.g. a short time period, like two days)`
		`+ where they can commit other enhancements`
		`+ (to save users lots of upgrades)`
		`+ or to discuss the committed change`
		`+ before its actually pushed to the users.`
		`+ With the current (FC7T1) scheme it means:`
		`+ don't build the package immediately.`
		`+ (In the future with the new repo push stuff from lmacken`
		`+ it hopefully should be easily possible`
		`+ to define a waiting period in updates-testing`
		`+ before a package gets pushed out to the proper repo.)`
		`+ Only the per-distribution maintainer`
		`+ should commit and build medium sized changes.`
		`+ Those should be tested in devel first`
		`+ and co-maintainers should have a chance`
		`+ to comment on the commits`
		`+ before the package gets in the repo.`
		`+ Big changes get coordinated.`

		`* The usual rules for xref:Who_is_allowed_to_modify_which_packages.adoc[Who is Allowed to Modify Which Packages] remain intact.`
		`- Thus people from QA, Security or Arch-SIGs might touch the package, too.`
		`- There is the strong wish to have`
		`- a group of long-term contributors`
		`- (say FESCo members, Release-Managers, Sponsors and some other hand-selected people)`
		`- that get access everywhere`
		`- to commit package updates easily`
		`- without asking the maintainers,`
		`- in case the maintainers are not fixing stuff`
		`- or if the changes are small and obvious`
		`- (it's often a lot easier to commit a simple spec files touch`
		`- than to create a patch, send it to the maintainer or open bugzilla).`
		`+ Thus people from QA, Security or Arch-SIGs might touch the package, too.`
		`+ There is the strong wish to have`
		`+ a group of long-term contributors`
		`+ (say FESCo members, Release-Managers, Sponsors and some other hand-selected people)`
		`+ that get access everywhere`
		`+ to commit package updates easily`
		`+ without asking the maintainers,`
		`+ in case the maintainers are not fixing stuff`
		`+ or if the changes are small and obvious`
		`+ (it's often a lot easier to commit a simple spec files touch`
		`+ than to create a patch, send it to the maintainer or open bugzilla).`

		`* The primary maintainer has to approve new co-maintainers.`
		`- They now and then should search for co-maintainers`
		`- if there aren't enough.`
		`+ They now and then should search for co-maintainers`
		`+ if there aren't enough.`

		`[[coordination_between_maintainers]]`
		`=== Coordination between maintainers`
		`@@ -231,13 +228,13 @@`
		`but here are some suggestions:`

		`* if two maintainers are in disagreement over a detail,`
		`- ask the third maintainer`
		`+ ask the third maintainer`

		`* if no consensus can be found,`
		`- ask on the appropriate mailing list`
		`+ ask on the appropriate mailing list`

		`* if still no consensus can be found,`
		`- ask a FESCo member to mediate`
		`+ ask a FESCo member to mediate`

		`If co-maintainers get the impression`
		`that the primary maintainer is a lame duck`
		`@@ -317,9 +314,7 @@`

		`We had some situations`
		`where maintainers had to stop maintaining packages in Fedora.`
		`- That can happen due to different circumstances`
		`- -- sicknesses,`
		`- accidents,`
		`+ That can happen due to different circumstances -- sicknesses, accidents,`
		`changes in the job or at home`
		`are only some examples of reasons to stop.`
		`Some of those situations happen suddenly`
		`@@ -335,8 +330,7 @@`
		`SIGs cannot be co-maintainers.`
		`Rather they should observe the packages`
		`or make sure that the SIG members are co-maintainers where needed.`
		`- That`
		`- -- if properly used --`
		`+ That -- if properly used --`
		`is nearly the same as having a SIG as a co-maintainer`
		`and avoids people suddenly`
		`getting an access to a lot of packages`
		`@@ -368,8 +362,7 @@`
		`to try and help solve them.`

		`Ask upstream developers`
		`- to become a co-maintainer or an observer of the package`
		`- -- that could benefit both sides.`
		`+ to become a co-maintainer or an observer of the package -- that could benefit both sides.`
		`Having upstream developers as primary maintainers`
		`is often better avoided`
		`(but is allowed).`
		`@@ -399,24 +392,24 @@`
		`as the infrastructure for it is pretty much in place.`

		`* The general and primary-maintainers for each release`
		`- are typically identical`
		`- (exception: EPEL);`
		`- it is the one that listed as the devel branch maintainer`
		`- in packagedb.`
		`+ are typically identical`
		`+ (exception: EPEL);`
		`+ it is the one that listed as the devel branch maintainer`
		`+ in packagedb.`

		`* Co-maintainers typically`
		`- have all the same privileges`
		`- as the primary maintainer,`
		`- but may only have them`
		`- on their own specific branch.`
		`+ have all the same privileges`
		`+ as the primary maintainer,`
		`+ but may only have them`
		`+ on their own specific branch.`

		`* Ideally, all packages should have at least two co-maintainers.`

		`* The package database should contain all the info`
		`- about maintainers and co-maintainers for each package.`
		`+ about maintainers and co-maintainers for each package.`

		`* Co-maintainers should have the permissions to build and push updates`
		`- as the maintainer does.`
		`+ as the maintainer does.`

		`=== Procedure`

fesco/modules/ROOT/pages/Updates_Policy.adoc

file modified

+5 -5

		`@@ -447,14 +447,14 @@`
		`The push may be either by the maintainer, or automatically by Bodhi:`

		`* The update becomes eligible for being pushed manually after reaching the _minimum_ "Stable by Karma" threshold`
		`- for Critical path updates (yes, the same limit applies to both types of updates),`
		`- OR the _minimum_ "Stable by Time" threshold.`
		`+ for Critical path updates (yes, the same limit applies to both types of updates),`
		`+ OR the _minimum_ "Stable by Time" threshold.`
		`* The update will be pushed automatically by Bodhi after reaching the _configured_ "Stable by Karma" threshold,`
		`- OR the _configured_ "Stable by Time" threshold,`
		`- if enabled ("Auto-request stable based on karma?" and "Auto-request stable based on time?").`
		`+ OR the _configured_ "Stable by Time" threshold,`
		`+ if enabled ("Auto-request stable based on karma?" and "Auto-request stable based on time?").`
		`* If the update has _any_ negative karma, the automatic push is disabled.`
		`* If the update reaches the "Unstable by Karma" threshold, it will be unpushed,`
		`- i.e. removed from the _updates-testing_ repository.`
		`+ i.e. removed from the _updates-testing_ repository.`

		`The maintainer is free to set the thresholds, but they cannot be lower than the minimum values described below,`
		`enforced by Bodhi.`

fesco/modules/ROOT/pages/Who_is_allowed_to_modify_which_packages.adoc

file modified

+48 -48

		`@@ -32,13 +32,13 @@`
		`* a packager doesn't fix important bugs in time`

		`* there are problems known that might be bad for the whole Project`
		`- or to a lot of users of the repo/a particular package`
		`+ or to a lot of users of the repo/a particular package`

		`* the changes are quite minor`
		`- or considered as a general cleanup to a lot of packages`
		`+ or considered as a general cleanup to a lot of packages`

		`* the changes are part of a Fedora Objective,`
		`- with a specific plan approved by FESCo`
		`+ with a specific plan approved by FESCo`

		`[[details]]`
		`== Details`
		`@@ -54,19 +54,19 @@`
		`The packager normally should keep track of his packages. That means:`

		`* respond in bugs reported in bugzilla,`
		`- especially fast if it's a serious problem like a security issue`
		`+ especially fast if it's a serious problem like a security issue`

		`* fix his stuff without explicit poking`
		`- if it is mentioned in the problem reports somewhere`
		`- -- that includes:`
		`+ if it is mentioned in the problem reports somewhere`
		`+ -- that includes:`

		`** fix EVR problems, when they get mentioned in problem reports`

		`** fix dependency issues (including those in the devel repo)`
		`- -- the script sends problems to both the maintainer and the list`
		`+ -- the script sends problems to both the maintainer and the list`

		`** participate in mass-rebuilds`
		`- and fix xref:Fails_to_build_from_source_Fails_to_install.adoc[Fails to Build from Source] bugs`
		`+ and fix xref:Fails_to_build_from_source_Fails_to_install.adoc[Fails to Build from Source] bugs`

		`If the packager doesn't keep track of those items,`
		`then other experienced packagers are free to fix stuff for them.`
		`@@ -78,57 +78,57 @@`
		`* security problems:`

		`** Important stuff should be fixed as quickly if possible`
		`- -- waiting one day for the maintainer to show up`
		`- and step in to fix a issue that got reported to them`
		`- is considered more than enough;`
		`- there may even be situations where issues need to be fixed quicker`
		`+ -- waiting one day for the maintainer to show up`
		`+ and step in to fix a issue that got reported to them`
		`+ is considered more than enough;`
		`+ there may even be situations where issues need to be fixed quicker`

		`** not that important problems should be dealt with quickly, too`
		`- -- waiting for 2-7 days (depending how bad the issue is) is considered enough`
		`+ -- waiting for 2-7 days (depending how bad the issue is) is considered enough`

		`* bugs needing similar treatment like security problems:`

		`** Important stuff`
		`- (data corruption for users)`
		`- should be fixed as quick if possible`
		`- -- waiting one day is considered more than enough here, too`
		`+ (data corruption for users)`
		`+ should be fixed as quick if possible`
		`+ -- waiting one day is considered more than enough here, too`

		`** harmful, but not that bad bugs that might hurt users`
		`- -- waiting for 2-14 days (depending how bad the issue is) is considered enough`
		`+ -- waiting for 2-14 days (depending how bad the issue is) is considered enough`

		`** annoying, but not that harmful bugs`
		`- -- waiting for 21 days is considered enough`
		`+ -- waiting for 21 days is considered enough`

		`Some notes:`

		`* If a packager is offline`
		`- for longer time periods (for example five days or longer)`
		`- due to vacation, traveling or other issues`
		`- they may announce that on the https://calendar.fedoraproject.org/vacation/[vacation calendar].`
		`- In this case, others know not to expect an answer before the packager returns`
		`- and can immediately proceed to fix things`
		`- (e.g. if a Security Fix needs to be applied).`
		`+ for longer time periods (for example five days or longer)`
		`+ due to vacation, traveling or other issues`
		`+ they may announce that on the https://calendar.fedoraproject.org/vacation/[vacation calendar].`
		`+ In this case, others know not to expect an answer before the packager returns`
		`+ and can immediately proceed to fix things`
		`+ (e.g. if a Security Fix needs to be applied).`

		`* Unhandled actually really means completely unhandled`
		`- -- if the maintainer responded once in a bug report,`
		`- but fell silent afterwards,`
		`- try to ping them again,`
		`- maybe they have just forgotten about this bug.`
		`- Or there might be some good reason`
		`- why they have not yet committed the provided fix.`
		`+ -- if the maintainer responded once in a bug report,`
		`+ but fell silent afterwards,`
		`+ try to ping them again,`
		`+ maybe they have just forgotten about this bug.`
		`+ Or there might be some good reason`
		`+ why they have not yet committed the provided fix.`

		`* If you committed changes to another package`
		`- wait some hours if possible`
		`- (normally 24 or 48)`
		`- before you actually build the updated package`
		`- as long it is nothing serious that should be fixed quickly`
		`- (security problems, ...).`
		`- That leaves some time for the maintainer to wake up.`
		`+ wait some hours if possible`
		`+ (normally 24 or 48)`
		`+ before you actually build the updated package`
		`+ as long it is nothing serious that should be fixed quickly`
		`+ (security problems, ...).`
		`+ That leaves some time for the maintainer to wake up.`

		`* Experienced packagers should limit their changes to other people packages`
		`- to things that are well agreed upon.`
		`- I.e. don't fix things considered somewhat controversial`
		`- or a matter of style.`
		`+ to things that are well agreed upon.`
		`+ I.e. don't fix things considered somewhat controversial`
		`+ or a matter of style.`

		`[[minor_general_or_cleanup_changes]]`
		`=== Minor, general or cleanup changes`
		`@@ -141,17 +141,17 @@`
		`Some examples of situations where bypassing the proper maintained is considered fine:`

		`* support for a new architecture`
		`- -- that often requires that a lot of packages`
		`- need adjustments or patches that packagers often can't even test themself.`
		`- Getting all those modifications in via bugzilla is a lot of annoying work,`
		`- so these things can be fixed directly in rawhide without contacting the individual maintainers`
		`- if the general effort was announced beforehand.`
		`- A SIG should handle the stuff`
		`- and continue with normal operations`
		`- after the initial porting efforts are finished.`
		`+ -- that often requires that a lot of packages`
		`+ need adjustments or patches that packagers often can't even test themself.`
		`+ Getting all those modifications in via bugzilla is a lot of annoying work,`
		`+ so these things can be fixed directly in rawhide without contacting the individual maintainers`
		`+ if the general effort was announced beforehand.`
		`+ A SIG should handle the stuff`
		`+ and continue with normal operations`
		`+ after the initial porting efforts are finished.`

		`* small fixes or adjustments for new or modified packaging guidelines`
		`- can be done directly in Git after being announced some days in advance.`
		`+ can be done directly in Git after being announced some days in advance.`

		`* mass rebuilds.`

jibecfed commented 2 years ago

this minor format issue creates useless log warning when running localization script on fedora documentation system (and prevent me to see real problems because of the spam), here is a fix to save about 1000 lines of spam.

oturpe commented 2 years ago

Hmm, most of the parts where you need changes were submitted by me.
As far as I know, all of that is valid AsciiDoc.
Also, the tools included in this repository,
build.sh, preview.sh and Makefile
read these without any warnings.
What exactly is the script that you are running?
I would like to understand what is happening better.
Maybe there is are different Asciidoc implementations,
or some kind of linter involved?

That said, I do not have anything against the proposed changes.
It would be good if the included tools would warn about these, though,
so this would not happen again.

jibecfed commented 2 years ago

The warning comes from: https://github.com/mquinson/po4a/blob/master/lib/Locale/Po4a/AsciiDoc.pm#L965

last time I did this manual correction of asciidoc content was 12 or 18 months ago, it's not big deal, but over time it creates a huge load of log.

10 indentation "errors" creates 10 lines of log for the source file, and 10 lines per language who started the translation. Over time, there is more and more languages, and it becomes too much :p

oturpe commented 2 years ago

Sure, removing warnings is good.
I am just wondering
if it is a good idea for a translation tool like that
to emit warnings about valid input?
I will check Po4a issues
and write something in there if I can.

Could you also explain what warning comes from cases like this,
where a line within a paragraph starts with --?
That is just the mdash character,
I cannot find anything in the AsciiDoc spec
that would give it a different meaning
and Antora renders it correctly, too.

oturpe commented 2 years ago

I will check Po4a issues and write something in there if I can.

https://github.com/mquinson/po4a/issues/315

Pull-Request has been merged by zbyszek

2 years ago

oturpe commented 2 years ago

I will check Po4a issues and write something in there if I can.

https://github.com/mquinson/po4a/issues/315

This issue has been resolved,
there is a new option nolinting in po4a.
So if localization wants to avoid doing fixes like this one,
such option will be available in the next po4a release.
Reference: po4a/pull/322.