From edf1088a26653b85a70bf5dc2e6a1494c3581d43 Mon Sep 17 00:00:00 2001 From: Peter Turcan Date: Tue, 18 Apr 2023 15:21:21 -0700 Subject: [PATCH] 4 doc navigation --- contributor-guide/modules/ROOT/nav.adoc | 2 +- .../modules/ROOT/pages/index.adoc | 3 + .../modules/ROOT/pages/intro.adoc | 46 +++++++- formal-reviews/modules/ROOT/nav.adoc | 2 +- formal-reviews/modules/ROOT/pages/intro.adoc | 105 +++++++++++++++++- release-process/modules/ROOT/nav.adoc | 2 +- release-process/modules/ROOT/pages/intro.adoc | 56 +++++++++- user-guide/modules/ROOT/nav.adoc | 11 +- user-guide/modules/ROOT/pages/index.adoc | 8 +- user-guide/modules/ROOT/pages/intro.adoc | 8 +- 10 files changed, 227 insertions(+), 16 deletions(-) diff --git a/contributor-guide/modules/ROOT/nav.adoc b/contributor-guide/modules/ROOT/nav.adoc index 7508ab4..2ba3aa3 100644 --- a/contributor-guide/modules/ROOT/nav.adoc +++ b/contributor-guide/modules/ROOT/nav.adoc @@ -1,2 +1,2 @@ -* X +xref:intro.adoc[Introduction to becoming a Boost Contributor] diff --git a/contributor-guide/modules/ROOT/pages/index.adoc b/contributor-guide/modules/ROOT/pages/index.adoc index cb6de64..5b45d14 100644 --- a/contributor-guide/modules/ROOT/pages/index.adoc +++ b/contributor-guide/modules/ROOT/pages/index.adoc @@ -1,4 +1,5 @@ = Contributor Guide + :toc: left :toclevels: 3 :idprefix: @@ -8,3 +9,5 @@ :nofooter: :sectlinks: :doctype: article + +xref:intro.adoc[Introduction to becoming a Boost Contributor] diff --git a/contributor-guide/modules/ROOT/pages/intro.adoc b/contributor-guide/modules/ROOT/pages/intro.adoc index 64a26b2..a48cd3d 100644 --- a/contributor-guide/modules/ROOT/pages/intro.adoc +++ b/contributor-guide/modules/ROOT/pages/intro.adoc @@ -1,7 +1,47 @@ -= Introduction :idprefix: :idseparator: - :leveloffset: +1 -Boost is a collection of peer-reviewed and high-quality libraries that aim to -make application development simple and straight-forward for everyone! += Introduction to becoming a Boost Contributor + +This section describes the requirements and guidelines for the content of a library submitted to Boost. + +Boost developers constitute a wide array of people throughout much of the world. Over the years much work has gone into the quantity and quality of the C++ libraries and tools that make up Boost. There are many ways to become part of the Boost developer community, all starting with getting involved in the development discussion. But if you are looking for an + easier place to start than developing a library, consider volunteering as a tester. + +As a first step to developing a library, read the Requirements Overview for Boost. + +== Requirements Overview + +To avoid a proposed library being rejected, it must meet these requirements: + +. The license must meet the <>. Restricted licenses like the GPL and LGPL are not acceptable. +. The <> must be clear. +. The library should be useful to a general audience. +. The library must meet the <>. +. The library should preferably meet the <>. But is only required to meet them after acceptance. +. The library must come reasonably close to meeting the + <>. +. The author must be willing to participate in discussions + on the mailing list, and to refine the library accordingly. + +TIP:: There's no requirement that an author read the mailing list + for a time before making a submission. It has been noted, + however, that submissions which begin "I just started to read + this mailing list ..." seem to fail, often embarrassingly. + +== License Requirements + +== Copyright Ownership + +== Portability Requirements + +== Organization Requirements + +== Design Guidelines + +== See Also + +* https://stage.antora.cppalliance.org/doc/user-guide/index.html[User Guide] +* https://stage.antora.cppalliance.org/doc/formal-reviews/intro.html[Formal Reviews] +* https://stage.antora.cppalliance.org/doc/release-process/intro.html[Release Process] \ No newline at end of file diff --git a/formal-reviews/modules/ROOT/nav.adoc b/formal-reviews/modules/ROOT/nav.adoc index 518ef7e..94766e8 100644 --- a/formal-reviews/modules/ROOT/nav.adoc +++ b/formal-reviews/modules/ROOT/nav.adoc @@ -1 +1 @@ -* xref:intro.adoc[] +* xref:intro.adoc[Introduction to Boost Formal Reviews] diff --git a/formal-reviews/modules/ROOT/pages/intro.adoc b/formal-reviews/modules/ROOT/pages/intro.adoc index 83fc374..22fa9b3 100644 --- a/formal-reviews/modules/ROOT/pages/intro.adoc +++ b/formal-reviews/modules/ROOT/pages/intro.adoc @@ -1 +1,104 @@ -= intro += Introduction to Boost Formal Reviews + +When you feel that your library is ready for entry into Boost, + you need to find at least one member (but preferably several) of + the Boost community who is willing to publicly endorse your + library for entry into Boost. A simple method of achieving this + is to post to the https://www.boost.org/community/groups.html[Boost + developers mailing list] a short description of your + library, links to its Github and documentation, and a request for + endorsements. + +It is expected that those who endorse a library for review + will have performed at least a cursory check of the library's + suitability for Boost in terms of documentation, fit with + the rest of Boost and usefulness. A public endorsement of a + library for review means that from an initial glance, they + believe that the library has a reasonable chance to be accepted + during a formal review. The expectation is that these endorsers + will themselves review of the library during formal review + period, though this is not binding. + +Once you have a list of people who have publicly endorsed + your library for review, email the https://www.boost.org/community/reviews.html#Wizard[Review Wizards] to request that your library be added to the https://www.boost.org/community/review_schedule.html[Boost Formal Review Schedule] where the following information will be shown: + +[circle] +* Submission +* Submitter +* Links to Source (GitHub), Documentation (HTML website) + and any Incubator entry +* Review Manager +* Review Dates + + +== Seek a Review Manager + +In order to schedule a formal review, the author must find a + capable volunteer to manage the review. This should be someone + with knowledge of the library domain, and experience with the + review process. See https://stage.antora.cppalliance.org/doc/formal-reviews/intro.html[Formal Reviews] for the responsibilities of the review manager. + +Authors can find community members interested in managing + reviews through discussion of the library on the developer + list. If no one steps forward to volunteer to manage the + review, it is appropriate to contact an experienced Boost + member who showed interest in the library. Be considerate that + managing a review is a serious commitment; for this reason, + it's better to contact the member off-list. + +If you cannot find a review manager after 3 weeks using the + means above, and your submission is targeting eventual + standardization, there is a list of Boost regulars who are also + WG21 committee members who have volunteered to act as review + managers in such cases. Please try them in the order listed: + + . Zach Laine + . Micheal Caisse + . Matt Calabrese + . EdwardDiener + . Louis Dionne + . Vinnie Falco + . Glen Fernandes + . David Sankel + + +Once a potential review manager has been identified, contact the https://www.boost.org/community/reviews.html#Wizard[Review Wizards] for approval. The wizards approve review managers based on their level of participation in the Boost community. + +The review wizards will coordinate with both the author and + review manager to schedule a date convenient for both. + +== Formal Review + +Before your formal review begins, double-, triple-, and + quadruple-check your library. Verify that every code example + works, that all unit tests pass on at least two compilers on at + least two major operating systems, and run your documentation + through a spelling and grammar checker. + +Please do not modify your library on its *master* branch + during a review. Instead, modify a separate *develop* branch in + response to feedback and reviews. For bigger ticket items of + work, open issues on your issue tracker so interested people can + track the fixing of specific issues raised. + +The review manager will consider all the reviews made by + members of the community and arrive at a decision on + whether your library is rejected, conditionally accepted or + unconditionally accepted. They will post a report summarizing + the decision publicly. If conditions are attached to + acceptance, you will need to implement those conditions or + else undergo an additional formal review. + +== Boost web site posting + +Once an accepted library is ready for inclusion on the Boost + web site, the submitter is typically given Boost repository + write access, and expected to check-in and maintain the library + there. Contact the moderators if you need write access or + direct use of the repository isn't possible for you. + +== See Also + + * https://stage.antora.cppalliance.org/doc/user-guide/index.html[User Guide] +* https://stage.antora.cppalliance.org/doc/contributor-guide/index.html[Contributor Guide] +* https://stage.antora.cppalliance.org/doc/release-process/intro.html[Release Process] \ No newline at end of file diff --git a/release-process/modules/ROOT/nav.adoc b/release-process/modules/ROOT/nav.adoc index 518ef7e..c70ca3e 100644 --- a/release-process/modules/ROOT/nav.adoc +++ b/release-process/modules/ROOT/nav.adoc @@ -1 +1 @@ -* xref:intro.adoc[] +* xref:intro.adoc[Introduction to the Boost Release Process] diff --git a/release-process/modules/ROOT/pages/intro.adoc b/release-process/modules/ROOT/pages/intro.adoc index 83fc374..0c8cc2c 100644 --- a/release-process/modules/ROOT/pages/intro.adoc +++ b/release-process/modules/ROOT/pages/intro.adoc @@ -1 +1,55 @@ -= intro += Introduction to the Boost Release Process + +The Boost libraries are released publicly three times per year: + +[circle] +* 2nd April +* 2nd August +* 2nd December + +Each release will contain updates to existing libraries, and some releases will contain new libraries. The release is built from the *master* branch of Boost's GitHub site: xxxxxx + +== Milestones in the Release Cycle + +There is a strict countdown to a public release. + +7 Weeks Prior to Release Date:: + +The *master* branch is closed to all check ins, except bug fixes and quality checks. + +6 Weeks Prior to Release Date:: + +The *master* branch is closed to major code changes. There can be no rewrites of code, even to fix issues. + +5 Weeks Prior to Release Date:: + +The *master* branch is closed to all check ins, except with permission from the release committee. + +4 days Prior to Beta Release Date:: + +The *master* branch is closed. Beta release candidates are built. + +4 Weeks Prior to Release Date:: + +The Beta release is published to the Boost site. The *master* branch is opened to small bug fixes and documentation changes. Permission from the release committee is required for larger changes. + +1 Week Prior to Release Date:: + +The *master* branch is closed to all check ins, except high-priority fixes. + +4 Days Prior to Release Date:: + +The *master* branch is closed. Release candidates are built. + +Day of Release:: + +The release candidate is published to the Boost site. The *master* branch is opened for all check ins. + ++ +If issues are found with a release candidate that are important enough to address quickly (that is, before the next full public release), then a point release will be built when fixes are available and tested. This will not typically result in the *master* branch being closed to other check ins. + +== See Also + +* https://stage.antora.cppalliance.org/doc/user-guide/index.html[User Guide] +* https://stage.antora.cppalliance.org/doc/contributor-guide/index.html[Contributor Guide] +* https://stage.antora.cppalliance.org/doc/formal-reviews/intro.html[Formal Reviews] diff --git a/user-guide/modules/ROOT/nav.adoc b/user-guide/modules/ROOT/nav.adoc index b123ac0..a55663e 100644 --- a/user-guide/modules/ROOT/nav.adoc +++ b/user-guide/modules/ROOT/nav.adoc @@ -1,9 +1,8 @@ -* New Content -** xref:intro.adoc[Introduction] -** xref:getting-started-with-windows.adoc[Getting Started with Windows] -** xref:getting-started-with-linux.adoc[Getting Started with Linux] -** xref:use-boost-with-windows-package-manager.adoc[Use Boost with Windows and a Package Manager] -** xref:use-boost-with-linux-package-manager.adoc[Use Boost with Linux and a Package Manager] +* xref:intro.adoc[Introduction to Boost] +* xref:getting-started-with-windows.adoc[Getting Started with Windows] +* xref:getting-started-with-linux.adoc[Getting Started with Linux] +* xref:use-boost-with-windows-package-manager.adoc[Use Boost with Windows and a Package Manager] +* xref:use-boost-with-linux-package-manager.adoc[Use Boost with Linux and a Package Manager] * Legacy Content ** xref:prev/borland_cpp.adoc[] ** xref:prev/bugs.adoc[] diff --git a/user-guide/modules/ROOT/pages/index.adoc b/user-guide/modules/ROOT/pages/index.adoc index 01f8a70..e2ac099 100644 --- a/user-guide/modules/ROOT/pages/index.adoc +++ b/user-guide/modules/ROOT/pages/index.adoc @@ -1 +1,7 @@ -= User Guide \ No newline at end of file += User Guide + +* xref:intro.adoc[Introduction to Boost] +* xref:getting-started-with-windows.adoc[Getting Started with Windows] +* xref:getting-started-with-linux.adoc[Getting Started with Linux] +* xref:use-boost-with-windows-package-manager.adoc[Use Boost with Windows and a Package Manager] +* xref:use-boost-with-linux-package-manager.adoc[Use Boost with Linux and a Package Manager] diff --git a/user-guide/modules/ROOT/pages/intro.adoc b/user-guide/modules/ROOT/pages/intro.adoc index 88c62d1..c407dca 100644 --- a/user-guide/modules/ROOT/pages/intro.adoc +++ b/user-guide/modules/ROOT/pages/intro.adoc @@ -2,7 +2,7 @@ :idseparator: - :leveloffset: +1 -= Introduction += Introduction to Boost Boost is a collection of peer-reviewed and high-quality libraries that aim to make application development more productive for all C++ developers. @@ -84,3 +84,9 @@ If you are new to Boost, the recommended next step is to download the entire lib [square] * xref:getting-started-with-windows.adoc[Getting Started with Windows] * xref:getting-started-with-linux.adoc[Getting Started with Linux] + +== See Also + +* https://stage.antora.cppalliance.org/doc/contributor-guide/index.html[Contributor Guide] +* https://stage.antora.cppalliance.org/doc/formal-reviews/intro.html[Formal Reviews] +* https://stage.antora.cppalliance.org/doc/release-process/intro.html[Release Process] \ No newline at end of file