From 97cceff243d988b91258dbf1b6cf1f0a4bd65f5c Mon Sep 17 00:00:00 2001 From: Jenni Nikolaenko Date: Thu, 19 Jan 2023 17:43:07 +0200 Subject: Documentation: add contributing information Hello there! I decided to create a patch from my drafts so this information will not be lost. It still needs some attention. It is a good idea to have the documentation in one place. For us this means that information from these pages https://spectrum-os.org/contributing.html, https://spectrum-os.org/participating.html -- should be moved here https://spectrum-os.org/participating.html. What I did particularly: 1. Added a new chapter "Contributing". Copied here the information from here https://spectrum-os.org/contributing.html, adapting a bit to Spectrum Docs. 2. Moved the "Building Documentation" section from "Development" to "Contributing". 3. In the "Contributing" chapter you can find the following structure: - Communication in Spectrum (copied from https://spectrum-os.org/participating.html) - Documentation Style Guide - Building Documentation I tried to fix all cross-reference links, so this new content can be used right now. Any further updates are very welcome. Signed-off-by: Jenni Nikolaenko Message-Id: <20230119154307.28303-1-evgeniia.nikolaenko@unikie.com> Reviewed-by: Alyssa Ross Signed-off-by: Alyssa Ross --- .../contributing/building-documentation.adoc | 52 +++++++++++ Documentation/contributing/communication.adoc | 89 ++++++++++++++++++ Documentation/contributing/index.adoc | 95 +++++++++++++++++++ .../contributing/writing_documentation.adoc | 104 +++++++++++++++++++++ 4 files changed, 340 insertions(+) create mode 100644 Documentation/contributing/building-documentation.adoc create mode 100644 Documentation/contributing/communication.adoc create mode 100644 Documentation/contributing/index.adoc create mode 100644 Documentation/contributing/writing_documentation.adoc (limited to 'Documentation/contributing') diff --git a/Documentation/contributing/building-documentation.adoc b/Documentation/contributing/building-documentation.adoc new file mode 100644 index 0000000..63a3038 --- /dev/null +++ b/Documentation/contributing/building-documentation.adoc @@ -0,0 +1,52 @@ += Building Documentation +:page-parent: Contributing +:page-nav_order: 3 + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Make sure you have https://nixos.org/download.html[Nix] installed. +You may also want to xref:../installation/binary-cache.adoc[configure the Spectrum +binary cache], to avoid having to wait for dependencies to compile on +your local system. + +. Get a copy of the Spectrum source code: ++ +[source,shell] +---- +git clone https://spectrum-os.org/git/spectrum +---- +. Enter the documentation directory: ++ +[source,shell] +---- +cd spectrum/Documentation +---- +. Enter the development environment: ++ +[source,shell] +---- +nix-shell -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz +---- +. In the development shell, do an initial build of the documentation +site: ++ +[source,shell] +---- +scripts/build.sh +---- +. Run a development server for previewing changes locally: ++ +[source,shell] +---- +jekyll serve +---- ++ +This will serve a local copy of the documentation at http://localhost:4000/. ++ +IMPORTANT: Jekyll does not handle rendering of the draw.io diagrams. If you +modify any of those, or add new ones, run `scripts/build.sh` again to do a full +rebuild of the site. + +After making changes to the documentation, see how to +xref:../development/first-patch.adoc[send your patch] and submit the changes for review. diff --git a/Documentation/contributing/communication.adoc b/Documentation/contributing/communication.adoc new file mode 100644 index 0000000..bb8aeb9 --- /dev/null +++ b/Documentation/contributing/communication.adoc @@ -0,0 +1,89 @@ += Communication in Spectrum +:description: Channels, announcements and so on. +:page-nav_order: 1 +:page-parent: Contributing + +// SPDX-FileCopyrightText: 2023 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +There are several places online in which announcements, +discussion, and collaboration happen. Rather than tell +you about them all at once, though, it is best to tell you +which ones are relevant to you, given how you would like +to participate (or not) in the project. + +Our primary methods of communication are mailing lists and IRC. +If this is not how you are used to interacting with free +software projects, *DON'T PANIC*. + +We provide instructions for how to get started, and several +different interfaces for you to choose from depending on what workflow +(web, mail, Atom, etc.) makes you most comfortable. Details of these +will be explained further on, but first, you should figure out what +communication channels are actually relevant for you. + +If you are interested in keeping up to date with announcements from +Spectrum's developers, subscribe to *announce@spectrum-os.org*. +You can discuss Spectrum and related topics in real time on IRC, or +more long-form on spectrum-announce (_discuss@spectrum-os.org_). +Finally, development work happens in Spectrum's +xref:https://spectrum-os.org/git/[source repositories], and is +discussed on spectrum-devel (_devel@spectrum-os.org_). + + +== Internet Relay Chat + +There is a single Internet Relay Chat (IRC) channel, +xref:ircs://irc.libera.chat:6697/spectrum[spectrum:libera.chat] +on xref:https://libera.chat/[Libera.Chat], for all kinds of Spectrum +discussions.You can also join through xref:https://matrix.org/[Matrix] as +xref:https://matrix.to/#/#spectrum:libera.chat[spectrum:libera.chat]. +If you are new to IRC, you might find Matrix the easiest way to get started. +The channel is *logged*, but the logs are not available online yet. + + +== Mailing Lists + +If you are interested in participating in the project, or even just +following along with it, the best thing to do is subscribe to one or +more of the Spectrum mailing lists. + +If mailing lists are not your thing, that is okay! Try the +xref:https://spectrum-os.org/lists/hyperkitty/[Web UI], which allows +you to interact with the mailing lists much like a modern web forum. + +Each list has xref:https://spectrum-os.org/lists/archives/[archives] +that can also be accessed via the web, NNTP or Atom. You are strongly +encouraged to mirror them. + +[cols="1,1"] +|=== + +|announce@spectrum-os.org +|This is a one-way list where announcements +from Spectrum's developers will be posted. + +You can subscribe +xref:https://spectrum-os.org/lists/mailman3/lists/announce.spectrum-os.org/[on the web], +or by sending mail to *announce-subscribe@spectrum-os.org*. + +|discuss@spectrum-os.org +|This list contains high-level discussion about the project. + +You can subscribe +xref:https://spectrum-os.org/lists/mailman3/lists/discuss.spectrum-os.org/[on the web], +or by sending mail to *discuss-subscribe@spectrum-os.org*. + +|devel@spectrum-os.org +|This list is where low-level technical discussions happen, +and where patches are sent. + +There is a separate guide for the Spectrum development process, +including how patches are sent to this list and discussed. +For more information, see +xref:../development/working-with-patches.adoc[Working with Patches]. + +You can subscribe +xref:https://spectrum-os.org/lists/mailman3/lists/devel.spectrum-os.org/[on the web], or by sending mail to *devel-subscribe@spectrum-os.org*. + +|=== diff --git a/Documentation/contributing/index.adoc b/Documentation/contributing/index.adoc new file mode 100644 index 0000000..4be8d69 --- /dev/null +++ b/Documentation/contributing/index.adoc @@ -0,0 +1,95 @@ += Contributing +:description: How to contribute changes to the Spectrum source repository. +:page-nav_order: 5 +:page-has_children: true + +// SPDX-FileCopyrightText: 2023 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Thank you so much for your interest in contributing to Spectrum. +Having a healthy community of people who feel empowered to work +on the project is vital to its success. + +If you have any questions about the project, please +xref:../contributing/communication.adoc[get in touch] with +the community. We will gladly help you out! + + +== Contributing Code + +If you are interested in contributing code to Spectrum, +you can find the source repositories online: https://spectrum-os.org/git/. + +If you have made changes you would like to be included +in the official Spectrum distribution, please send patches +to the spectrum-devel mailing list (devel@spectrum-os.org). +For more information, see +xref:../development/working-with-patches.adoc[Working with Patches]. + +Sending patches to the list is easy — you can do it with Git, +straight from the command line. You do not have to set anything up +in your email client, and you do not have to subscribe to the list. +The only thing you need to do is probably to set up Git so it knows +how to send email using your provider's SMTP server. +These instructions https://git-send-email.io/ should be enough +to get you going. If you are still stuck, send an email +to *devel@spectrum-os.org* and we will help you out. + +Once you have Git configured correctly, sending your changes to the +list should be as simple as something like: + +[listing] +[source,shell] +git send-email origin/master --to devel@spectrum-os.org + +You will be CCed on replies to your posts, so you do not even have to be +subscribed to the mailing list if you are worried about too much traffic. +There is also a web interface https://spectrum-os.org/lists/hyperkitty/ +that you can use to browse or even post to the mailing list. + +Add a Signed-off-by line to each patch you submit, to indicate your +certification of the xref:https://spectrum-os.org/git/spectrum/tree/DCO-1.1.txt[Developer's Certificate of Origin] for that patch. +The easiest way to do this is with `git commit's -s` flag. + +Do not be too afraid of getting it wrong the first couple of times. +This might well be a new way of collaborating for you, and everybody +understands that. Hopefully, you will soon realise just how effective +this style of collaboration can be compared to the alternatives. + +== Contributing Documentation + +If you notice something that can be fixed or improved: + +. xref:https://spectrum-os.org/doc/development/first-patch.html#making-changes[Edit or add any relevant documentation]. ++ +TIP: Make sure your changes are formatted correctly and consistently +with the rest of the documentation. For information on writing guidelines, +see xref:../contributing/writing_documentation.adoc[Documentation Style Guide]. ++ +. xref:../contributing/building-documentation.adoc[Test your documentation]. +Reread what you wrote and run a spellchecker on it to make sure you did not miss anything. +. xref:https://spectrum-os.org/doc/development/first-patch.html#submitting-changes[Submit changes]. + + +=== Documentation To-Do List + +Spectrum documentation needs are: + +* Reporting Bugs +* Development conventions/style (code review, naming) +* Integration, code philosophy + +The list will be updated. Improvements to the documentation are welcome! + +== Contributing Other Things + +At this stage, it is difficult to say what things would be useful +to the project beyond code and documentation. Artwork will be +extremely important and valuable. But, do not let that dissuade you! +At some point, we will need all sorts of things, and we might as well +get the work done early if people are willing to do it. + +If you think you have skills to offer the project beyond writing code, +we would love to hear from you. The best thing to do is to either talk +with us on spectrum-discuss, or in real time on IRC. +For more information, see xref:../contributing/communication.adoc[Communication in Spectrum]. diff --git a/Documentation/contributing/writing_documentation.adoc b/Documentation/contributing/writing_documentation.adoc new file mode 100644 index 0000000..a58da64 --- /dev/null +++ b/Documentation/contributing/writing_documentation.adoc @@ -0,0 +1,104 @@ += Documentation Style Guide +:description: Channels, announcements and so on. +:page-nav_order: 2 +:page-parent: Contributing + +// SPDX-FileCopyrightText: 2023 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Here you can find the standards we follow for writing, +formatting, and organizing the Spectrum documentation. +Please follow these guidelines and conventions +when editing the documentation. + +We use xref:https://nixos.org/manual/nix/stable/introduction.html[Nix] +and xref:https://github.com/just-the-docs/just-the-docs[Just the Docs] +for building the documentation. Sources are written in AsciiDoc +If you are new with it, +see xref:https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation]. + +If you want to test your changes, +see xref:../contributing/building-documentation.adoc[Building Documentation]. + +== Philosophy + +* 1 change = 1 patch +* Update the documentation with the code. +* Organize the AsciiDoc files into subdirectories. +* Keep separate documentation for every different process +to avoid confusion. +* Do not assume that readers know everything you currently know. +* Avoid jargon and acronyms, if you can. +* Avoid multiple variations or spellings to refer to the same +function, element, and so on. +* Write short and useful documents. Cut out everything unnecessary, +while also making a habit of continually improving every doc +to suit your changing needs. + + +== Document Layout + +* xref:https://docs.asciidoctor.org/asciidoc/latest/document/header/[Document header]: +include your name and a revision line following the author line. Example: + + = Document Title + :description: Some words about the content. + Author Name + v1.0, 2012-02-10 + //empty line that ends the document header + +* Licensing: include license information after a document header. For example: + + // SPDX-FileCopyrightText: year / Name, surname / email address or the company name + // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +* Double space: the double space after the period is deliberate. +Some people find it improves readability, and others do not like it, +but the reason we use it in Spectrum documentation is that it allows +text editors (Emacs) to differentiate between the ends of sentences +and abbreviations (like "etc."), which means that you can make commands +like "move to the next sentence" work accurately even if those +abbreviations are used. + +* Character line limit: +** Keep text hard-wrapped at 70-80 characters. (Most editors should be able +to do this automatically.) This makes it easier to pick out specific parts +in review, and also makes it easier to read in some editors. (It does not make a difference to the result as rendered in the web browser.) +** Keep the text in the description attribute hard-wrapped as well. For more information, see the xref:https://docs.asciidoctor.org/asciidoc/latest/document/metadata/#description[Document Metadata] section of the Asciidoctor Docs. + +* Put one sentence on each line. This makes it easy to move content around, and also easy to spot (too) long sentences. For more information, see xref:https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[AsciiDoc Recommended Practices]. + +== Structure + +* Use subheading to organize information. +* One topic per article. +* To make accents, use xref:https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/[admonitions]. +* Use numbered lists for actions that happen in sequence. +* Do not use parenthesis for additional information, make a separate sentence instead. + + +== Language + +=== Plain English + +Plain language is a universal language that makes information clear and better to understand. + +* Short, sharp sentences. +* Use simple tenses. +* Write in an active voice. +* Understandable language, fewer gerunds. +* Do not contract the words: use cannot instead of can’t. +* Write the full name when first mentioned with the acronym in brackets. +* Use numerals for numbers. +* Do not use Latin words. For example: +** perform operations, *etc.* => perform operations, *and so on* +** *e.g.* a Microsoft SQL Server => *for example,* a Microsoft SQL Server +** *via* the system => *through* the system + +=== Spelling + +* Use standard United States (U.S.) English. In cases where US spelling differs +from UK spelling, use the US spelling. There is no need to fix one by +replacing it with the other. +* When you use filenames, URLs, and data parameters in examples, try to avoid words that are spelled differently by different groups of English speakers. +* Use serial (Oxford) commas. -- cgit 1.4.1