diff --git a/.Rbuildignore b/.Rbuildignore deleted file mode 100644 index c503c4f6..00000000 --- a/.Rbuildignore +++ /dev/null @@ -1 +0,0 @@ -^\.github$ diff --git a/_quarto.yml b/_quarto.yml index 561939f2..baada4b3 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -10,33 +10,39 @@ book: repo-url: https://github.com/r-devel/rdevguide repo-branch: main repo-actions: [edit, issue] + sharing: [linkedin] + open-graph: true + image: img/cover_page_scriberia.png + downloads: [pdf, epub] chapters: - index.qmd - - introduction.qmd - - getting_started.qmd - - issue_tracking.qmd - - reporting_bugs.qmd - - submitting_feature_requests.qmd - - reviewing_bugs.qmd - - finding_the_source.qmd - - lifecycle_of_a_patch.qmd - - documenting.qmd - - message_translations.qmd - - testing_pre_release_r_versions.qmd - - r_core_developers.qmd - - where_to_get_help.qmd - - news_and_announcements.qmd - - developer_tools.qmd + - chapters/introduction.qmd + - chapters/getting_started.qmd + - chapters/issue_tracking.qmd + - chapters/reporting_bugs.qmd + - chapters/submitting_feature_requests.qmd + - chapters/reviewing_bugs.qmd + - chapters/finding_the_source.qmd + - chapters/lifecycle_of_a_patch.qmd + - chapters/documenting.qmd + - chapters/message_translations.qmd + - chapters/testing_pre_release_r_versions.qmd + - chapters/r_core_developers.qmd + - chapters/where_to_get_help.qmd + - chapters/news_and_announcements.qmd + - chapters/developer_tools.qmd format: html: - theme: cosmo - include-in-header: header.html + theme: + light: cosmo + dark: [cosmo, css/theme-dark.scss] + include-in-header: html/header.html description-meta: "This guide is a comprehensive resource for contributors (from all levels, beginners, intermediate, and seasoned) to the R project, facilitating their onboarding and helping them navigate the contribution process." pdf: documentclass: scrreprt - include-in-header: preamble.tex - include-before-body: frontpage.tex + include-in-header: tex/preamble.tex + include-before-body: tex/frontpage.tex epub: cover-image: img/cover_page_scriberia.png diff --git a/book.bib b/book.bib deleted file mode 100644 index f52f3d22..00000000 --- a/book.bib +++ /dev/null @@ -1,10 +0,0 @@ -@Book{xie2015, - title = {Dynamic Documents with {R} and knitr}, - author = {Yihui Xie}, - publisher = {Chapman and Hall/CRC}, - address = {Boca Raton, Florida}, - year = {2015}, - edition = {2nd}, - note = {ISBN 978-1498716963}, - url = {http://yihui.name/knitr/}, -} diff --git a/developer_tools.qmd b/chapters/developer_tools.qmd similarity index 100% rename from developer_tools.qmd rename to chapters/developer_tools.qmd diff --git a/documenting.qmd b/chapters/documenting.qmd similarity index 100% rename from documenting.qmd rename to chapters/documenting.qmd diff --git a/finding_the_source.qmd b/chapters/finding_the_source.qmd similarity index 100% rename from finding_the_source.qmd rename to chapters/finding_the_source.qmd diff --git a/getting_started.qmd b/chapters/getting_started.qmd similarity index 100% rename from getting_started.qmd rename to chapters/getting_started.qmd diff --git a/introduction.qmd b/chapters/introduction.qmd similarity index 98% rename from introduction.qmd rename to chapters/introduction.qmd index c3203735..009ba5f4 100644 --- a/introduction.qmd +++ b/chapters/introduction.qmd @@ -48,6 +48,6 @@ Maintainers and contributors are also requested to follow [this guide's code of This guide is built using Quarto which makes editing it easier, provided you have a GitHub account (sign-up at [github.com](https://github.com/)). After you log-in to GitHub, click on the ‘Edit this page’ (available in the left side column) link highlighted with a red ellipse in the image below. This will take you to an editable version of the the source R Markdown file that generated the page you are on: -![Screenshot of the toolbar in the HTML version of the guide, with the "Edit this page" link highlighted in red.](img/edit_icon.png) +![Screenshot of the toolbar in the HTML version of the guide, with the "Edit this page" link highlighted in red.](../img/edit_icon.png) Use the [issue tracker](https://github.com/r-devel/rdevguide/issues) to raise an issue about the guide’s content or to make a feature request. diff --git a/issue_tracking.qmd b/chapters/issue_tracking.qmd similarity index 93% rename from issue_tracking.qmd rename to chapters/issue_tracking.qmd index a5d38b22..d0a5f0d3 100644 --- a/issue_tracking.qmd +++ b/chapters/issue_tracking.qmd @@ -22,11 +22,11 @@ To get a Bugzilla account send an e-mail to `bug-report-request@r-project.org` f An image of the existing home page of Bugzilla is shared below: -![Screenshot of the existing home page of Bugzilla.](img/bugzilla.png) +![Screenshot of the existing home page of Bugzilla.](../img/bugzilla.png) On the home page of Bugzilla, there are various buttons and links. There are four square buttons called as: -![Screenshot of the four square buttons on the home page of Bugzilla.](img/squarebuttons.png) +![Screenshot of the four square buttons on the home page of Bugzilla.](../img/squarebuttons.png) 1. [File a bug](https://bugs.r-project.org/enter_bug.cgi): You will have to log in to Bugzilla to file a bug using this button @@ -46,18 +46,18 @@ Several useful shortcuts are available from the landing page: A [quick search](https://bugs.r-project.org/page.cgi?id=quicksearch.html) bar is available on the home page where you can enter a bug number to search or some search terms. -![Screenshot of the quick search bar on the home page of Bugzilla.](img/quicksearch.png) +![Screenshot of the quick search bar on the home page of Bugzilla.](../img/quicksearch.png) There is also a section for Common Queries on the home page which includes links to bugs reported and changed in the last 24 hours and last 7 days. -![Screenshot of the Common Queries section on the home page of Bugzilla.](img/commonquery.png) +![Screenshot of the Common Queries section on the home page of Bugzilla.](../img/commonquery.png) ## Searching for Bugs to Contribute to {#searching} When presented with a long list of bugs, it can often be a bit demotivating when it's not clear where to start. To help with this, you can use the [**Advanced Search**](https://bugs.r-project.org/query.cgi?format=advanced). -![Screenshot of Advanced Search page showing the following fields: Summary, Product, Component, Status, Resolution](img/bugzilla-adv-search-home.png) +![Screenshot of Advanced Search page showing the following fields: Summary, Product, Component, Status, Resolution](../img/bugzilla-adv-search-home.png) This presents several fields that you can use to narrow down your search. You can find out what a particular field is by clicking on the header, which will take you to that section in the [**Bug Fields Information Page**](https://bugs.r-project.org/page.cgi?id=fields.html). @@ -93,14 +93,14 @@ You can use this section to narrow down your search further to filter by things It can be helpful, for example, to search for bugs labelled with `HELPWANTED`, which indicates bugs that may be suitable for anyone to work on regardless of expertise. -![Screenshot of expanded Detailed Bug Information section showing the following fields: Comment, URL, Keywords (with HELPWANTED entered), Deadline, inclusion/exclusion of bug numbers, Version, Severity, Priority, Hardware, and OS](img/bugzilla-adv-search-detailed-bug-info.png) +![Screenshot of expanded Detailed Bug Information section showing the following fields: Comment, URL, Keywords (with HELPWANTED entered), Deadline, inclusion/exclusion of bug numbers, Version, Severity, Priority, Hardware, and OS](../img/bugzilla-adv-search-detailed-bug-info.png) ### Search By People {#searching-sbp} You can use this to narrow down your search to only include results of a specific person or up to three people who have participated in any component of the bug's discusson. -![Screenshot of expanded Search By People section showing three fields allowing you to enter a person's name who can be any of the bug assignee, the reporter, a CC list member, or a commenter](img/bugzilla-adv-search-search-by-people.png) +![Screenshot of expanded Search By People section showing three fields allowing you to enter a person's name who can be any of the bug assignee, the reporter, a CC list member, or a commenter](../img/bugzilla-adv-search-search-by-people.png) ### Search By Change History {#searching-sbch} @@ -108,4 +108,4 @@ You can use this to narrow down your search to only include results of a specifi Use this to search for bugs where any of the status fields has been changed (which, depending on the change, could indicate that someone from R-Core has given some attention to the bug). This also provides a date range to narrow your search. -![Screenshot of expanded Search by Change History section showing three fields: where ANY of the fields (multi-select list), changed to, and between (dates in YYYY-MM-DD format)](img/bugzilla-adv-search-search-by-change-history.png) +![Screenshot of expanded Search by Change History section showing three fields: where ANY of the fields (multi-select list), changed to, and between (dates in YYYY-MM-DD format)](../img/bugzilla-adv-search-search-by-change-history.png) diff --git a/lifecycle_of_a_patch.qmd b/chapters/lifecycle_of_a_patch.qmd similarity index 93% rename from lifecycle_of_a_patch.qmd rename to chapters/lifecycle_of_a_patch.qmd index b0687c5b..b4ee5223 100644 --- a/lifecycle_of_a_patch.qmd +++ b/chapters/lifecycle_of_a_patch.qmd @@ -59,32 +59,32 @@ Besides checking in your computer, you can use the Github mirror [r-devel/r-svn You should first find the file to edit, via the github interface for example: -![Screenshot of the heading of the src/library/stats/man/Mulinom.Rd](img/rsvn_file_to_edit.png "Opening the file to edit.") +![Screenshot of the heading of the src/library/stats/man/Mulinom.Rd](../img/rsvn_file_to_edit.png "Opening the file to edit.") Then you can edit it, directly in the interface or using the github interface: -![Screenshot of the file src/library/stats/man/Mulinom.Rd being edited via the Github interface](img/rsvn_edit_file.png "Editing a file via Github interface.") +![Screenshot of the file src/library/stats/man/Mulinom.Rd being edited via the Github interface](../img/rsvn_edit_file.png "Editing a file via Github interface.") Create a commit with a message describing the changes -![Screenshot of the commit message](img/rsvn_commit_message.png "Commiting the change in the file.") +![Screenshot of the commit message](../img/rsvn_commit_message.png "Commiting the change in the file.") And create a pull request from the branch created to check the changes. -![Screenshot of the message when opening a pull requests from the branch](img/rsvn_commit_pre_PR.png "Starting a pull requests with the changes previously committed.") +![Screenshot of the message when opening a pull requests from the branch](../img/rsvn_commit_pre_PR.png "Starting a pull requests with the changes previously committed.") Add a message and description of the svn for other users and the R core to know what is the purpose of this modification: -![Screenshot of the message and content while opening a pull requests for the r-svn repository](img/rsvn_PR_message.png "Describe the changes in the pull request.") +![Screenshot of the message and content while opening a pull requests for the r-svn repository](../img/rsvn_PR_message.png "Describe the changes in the pull request.") -![Screenshot of the pull requests opened](img/rsvn_PR_created.png "The result of opening a pull requests with the changes.") +![Screenshot of the pull requests opened](../img/rsvn_PR_created.png "The result of opening a pull requests with the changes.") Once the PR is submitted, some automatic checks will be triggered (they might need to be approved by some other users as per Github rules): -![Screenshot of the checks triggered by opening the pull request](img/rsvn_PR_automatic_checks.png "Automatic checks triggered in the r-devel/r-svn github repository.") +![Screenshot of the checks triggered by opening the pull request](../img/rsvn_PR_automatic_checks.png "Automatic checks triggered in the r-devel/r-svn github repository.") When the checks end you will need to explore the results and asses if the results indicate a problem or not. -![Screenshot of the results of the Github checks in the r-svn mirror](img/rsvn_checks_results.png "Summary of the results of the automatic checks triggered by opening the pull request.") +![Screenshot of the results of the Github checks in the r-svn mirror](../img/rsvn_checks_results.png "Summary of the results of the automatic checks triggered by opening the pull request.") Once you are happy with the changes and the checks report that everything is okay you can retrieve the patch via: diff --git a/message_translations.qmd b/chapters/message_translations.qmd similarity index 97% rename from message_translations.qmd rename to chapters/message_translations.qmd index 545a75a7..ca983d1c 100644 --- a/message_translations.qmd +++ b/chapters/message_translations.qmd @@ -245,7 +245,7 @@ the Windows Graphical User Interface. After selecting a component, you can select your preferred language. -![](img/translate_component.png) +![](../img/translate_component.png) @@ -257,7 +257,7 @@ After selecting a component, you can select your preferred language. - + **Step 3: Translate the Message** @@ -266,12 +266,12 @@ Now, you can click on Translate button on your right. > Note: More information for String status visit: > -![](img/translate_button.png) +![](../img/translate_button.png) Then, start translating the message by typing the translation in the text box. -![](img/translate_string_and_save.png) +![](../img/translate_string_and_save.png) - If you are **confident** that the **translation is correct**, make sure the "Needs editing" box is **unchecked**. @@ -294,7 +294,7 @@ text box. 2. Accept it if you think the automatic suggestion looks good -![](img/auto-suggestion.png) +![](../img/auto-suggestion.png) ------------------------------------------------------------------------ @@ -326,7 +326,7 @@ Instead of translating one string at a time, it is possible to bulk translate a 2. Select **'Tools > Automatic translation'** -![Tools drop-down menu with "Automatic Translations" selected](img/translate_automatic_translation.png) +![Tools drop-down menu with "Automatic Translations" selected](../img/translate_automatic_translation.png) 3. In the dialog, @@ -342,7 +342,7 @@ Instead of translating one string at a time, it is possible to bulk translate a [^09-message-translations-3]: Microsoft Translator is preferred for bulk translation as our free tier covers 2 million characters/month, where DeepL only allows 500k chars/month. If Microsoft Translator translations are much worse than DeepL, it may be useful to use it to translate one string at a time. -![Automatic Translations dialog box](img/translate_dialog.png) +![Automatic Translations dialog box](../img/translate_dialog.png) 4. Review the translations, edit as necessary and uncheck **"needing edit"**. diff --git a/news_and_announcements.qmd b/chapters/news_and_announcements.qmd similarity index 100% rename from news_and_announcements.qmd rename to chapters/news_and_announcements.qmd diff --git a/r_core_developers.qmd b/chapters/r_core_developers.qmd similarity index 100% rename from r_core_developers.qmd rename to chapters/r_core_developers.qmd diff --git a/reporting_bugs.qmd b/chapters/reporting_bugs.qmd similarity index 100% rename from reporting_bugs.qmd rename to chapters/reporting_bugs.qmd diff --git a/reviewing_bugs.qmd b/chapters/reviewing_bugs.qmd similarity index 100% rename from reviewing_bugs.qmd rename to chapters/reviewing_bugs.qmd diff --git a/submitting_feature_requests.qmd b/chapters/submitting_feature_requests.qmd similarity index 97% rename from submitting_feature_requests.qmd rename to chapters/submitting_feature_requests.qmd index 16b3045f..9c8acdd9 100644 --- a/submitting_feature_requests.qmd +++ b/chapters/submitting_feature_requests.qmd @@ -10,7 +10,7 @@ We recommend sharing your feature request idea on the [R-devel](https://stat.eth You can submit a feature request by [filing a bug](https://bugs.r-project.org/enter_bug.cgi) on Bugzilla. Under Component, select "Wishlist", the designated label for feature requests. -![The "Wishlist" component in Bugzilla's bug submission screen.](img/feature-requests.png) +![The "Wishlist" component in Bugzilla's bug submission screen.](../img/feature-requests.png) Similar to bugs, you should ensure that the feature request is [not already reported](#already-reported-bugs) and [follow best practices](#good-practices-bugs) whenever possible. diff --git a/testing_pre_release_r_versions.qmd b/chapters/testing_pre_release_r_versions.qmd similarity index 100% rename from testing_pre_release_r_versions.qmd rename to chapters/testing_pre_release_r_versions.qmd diff --git a/where_to_get_help.qmd b/chapters/where_to_get_help.qmd similarity index 100% rename from where_to_get_help.qmd rename to chapters/where_to_get_help.qmd diff --git a/css/theme-dark.scss b/css/theme-dark.scss new file mode 100644 index 00000000..881442d0 --- /dev/null +++ b/css/theme-dark.scss @@ -0,0 +1,8 @@ +/*-- scss:defaults --*/ +// Base document colors +$body-bg: #181818; +$body-color: white; +$link-color: #75AADB; + +// Code blocks +$code-block-bg-alpha: -.8; \ No newline at end of file diff --git a/header.html b/html/header.html similarity index 100% rename from header.html rename to html/header.html diff --git a/style.css b/style.css deleted file mode 100644 index 251d8cc6..00000000 --- a/style.css +++ /dev/null @@ -1,69 +0,0 @@ -@import url('https://fonts.googleapis.com/css2?family=Raleway&display=swap'); -@import url('https://fonts.googleapis.com/css2?family=Josefin+Slab&display=swap'); - -p.caption { - color: #777; - margin-top: 10px; -} - -p, code { - white-space: inherit; -} - -pre { - word-break: normal; - word-wrap: normal; -} - -pre, code { - white-space: inherit; -} - -p, div { - font-family: 'Raleway'; -} - -a { - font-family: 'Raleway'; -} - -h1, h2, h3, h4, h5, h6 { - font-family: 'Josefin Slab', serif; - color: #2673D9 !important; -} - -.summary { - background-color: white; -} - -a { - color: #2673D9 !important; -} - -/* these are Josh Comeau's amazing style!! */ -div.note { - position: relative; - padding: 1em; - margin: 2em 0; - background-size: 70px; - background: hsla(214, 70%, 50%, 0.15); - background-repeat: no-repeat; - background-position: 15px center; - border-left: solid 4px hsl(214, 70%, 50%) -} - -div.note.image { - content:url(img/information.svg); -} - -.note-icon { - height: 32px; - width: 32px; - position: absolute; - top: 0px; - left: 0px; - transform: translate(-50%, -50%); - background: white; - border-radius: 50%; - padding: 8px; -} diff --git a/frontpage.tex b/tex/frontpage.tex similarity index 100% rename from frontpage.tex rename to tex/frontpage.tex diff --git a/preamble.tex b/tex/preamble.tex similarity index 100% rename from preamble.tex rename to tex/preamble.tex