* [PATCH] Documentation: add contributing information
@ 2023-01-19 15:43 Jenni Nikolaenko
2023-01-20 17:28 ` Alyssa Ross
2023-01-20 17:32 ` Alyssa Ross
0 siblings, 2 replies; 3+ messages in thread
From: Jenni Nikolaenko @ 2023-01-19 15:43 UTC (permalink / raw)
To: devel; +Cc: Jenni Nikolaenko
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 <evgeniia.nikolaenko@unikie.com>
---
.../building-documentation.adoc | 6 +-
Documentation/contributing/communication.adoc | 89 +++++++++++++++
Documentation/contributing/index.adoc | 95 ++++++++++++++++
.../contributing/writing_documentation.adoc | 104 ++++++++++++++++++
Documentation/development/index.adoc | 7 +-
Documentation/development/uuid-reference.adoc | 2 +-
Documentation/index.adoc | 4 +-
7 files changed, 299 insertions(+), 8 deletions(-)
rename Documentation/{development => contributing}/building-documentation.adoc (90%)
create mode 100644 Documentation/contributing/communication.adoc
create mode 100644 Documentation/contributing/index.adoc
create mode 100644 Documentation/contributing/writing_documentation.adoc
diff --git a/Documentation/development/building-documentation.adoc b/Documentation/contributing/building-documentation.adoc
similarity index 90%
rename from Documentation/development/building-documentation.adoc
rename to Documentation/contributing/building-documentation.adoc
index 4f464f5..63a3038 100644
--- a/Documentation/development/building-documentation.adoc
+++ b/Documentation/contributing/building-documentation.adoc
@@ -1,6 +1,6 @@
= Building Documentation
-:page-parent: Development
-:page-nav_order: 5
+: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
@@ -49,4 +49,4 @@ 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:first-patch.adoc[send your patch] and submit the changes for review.
+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..8b92d56
--- /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*.
+
+|===
\ No newline at end of file
diff --git a/Documentation/contributing/index.adoc b/Documentation/contributing/index.adoc
new file mode 100644
index 0000000..71ffe0e
--- /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].
\ No newline at end of file
diff --git a/Documentation/contributing/writing_documentation.adoc b/Documentation/contributing/writing_documentation.adoc
new file mode 100644
index 0000000..9c1d5fb
--- /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 <author@example.org>
+ 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.
diff --git a/Documentation/development/index.adoc b/Documentation/development/index.adoc
index 1fccdd5..6b48418 100644
--- a/Documentation/development/index.adoc
+++ b/Documentation/development/index.adoc
@@ -15,13 +15,16 @@ Spectrum is free software, currently under active development.
* https://nixos.org/manual/nix/stable/introduction.html[Nix package manager]
* https://docs.asciidoctor.org/[AsciiDoc] for writing the documentation
+TIP: For information on writing guidelines,
+see xref:../contributing/writing_documentation.adoc[Documentation Style Guide].
+
== Mailing Lists
The Spectrum project runs several
-https://spectrum-os.org/participating.html#mailing-lists[mailing lists] on
+xref:../contributing/communication.adoc[mailing lists] on
which you can ask your questions or help other people with the questions they
have. All the Spectrum developers as well as many long time Linux and Spectrum users are on the lists.
For real-time feedback, use
-https://spectrum-os.org/participating.html#irc[IRC/Matrix channel].
+xref:../contributing/communication.adoc[IRC/Matrix channel].
diff --git a/Documentation/development/uuid-reference.adoc b/Documentation/development/uuid-reference.adoc
index 81300ee..5247726 100644
--- a/Documentation/development/uuid-reference.adoc
+++ b/Documentation/development/uuid-reference.adoc
@@ -55,6 +55,6 @@ The Spectrum installer system.
== Finding Undocumented UUIDs
-Running the Documentation/scripts/undocumented-uuids.sh script from
+Running the `Documentation/scripts/undocumented-uuids.sh` script from
the root of the Spectrum repository will scan the entire tree for
UUIDs not mentioned in this document.
diff --git a/Documentation/index.adoc b/Documentation/index.adoc
index 51a6e7d..cc25fd3 100644
--- a/Documentation/index.adoc
+++ b/Documentation/index.adoc
@@ -28,5 +28,5 @@ Once you are up and running, see
xref:development/index.adoc[Development] to understand how to work with
Spectrum's code and participate in the collaborative development process.
-If you are thinking of contributing to the Spectrum docs, see
- xref:development/building-documentation.adoc[Building Documentation].
+If you are thinking of contributing to the Spectrum code or docs, see
+ xref:contributing/index.adoc[Contributing].
--
2.34.1
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] Documentation: add contributing information
2023-01-19 15:43 [PATCH] Documentation: add contributing information Jenni Nikolaenko
@ 2023-01-20 17:28 ` Alyssa Ross
2023-01-20 17:32 ` Alyssa Ross
1 sibling, 0 replies; 3+ messages in thread
From: Alyssa Ross @ 2023-01-20 17:28 UTC (permalink / raw)
To: Jenni Nikolaenko, devel; +Cc: Jenni Nikolaenko
This patch has been committed as 97cceff243d988b91258dbf1b6cf1f0a4bd65f5c,
which can be viewed online at
https://spectrum-os.org/git/spectrum/commit/?id=97cceff243d988b91258dbf1b6cf1f0a4bd65f5c.
This is an automated message. Send comments/questions/requests to:
Alyssa Ross <hi@alyssa.is>
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] Documentation: add contributing information
2023-01-19 15:43 [PATCH] Documentation: add contributing information Jenni Nikolaenko
2023-01-20 17:28 ` Alyssa Ross
@ 2023-01-20 17:32 ` Alyssa Ross
1 sibling, 0 replies; 3+ messages in thread
From: Alyssa Ross @ 2023-01-20 17:32 UTC (permalink / raw)
To: Jenni Nikolaenko; +Cc: devel
[-- Attachment #1: Type: text/plain, Size: 1579 bytes --]
On Thu, Jan 19, 2023 at 05:43:07PM +0200, Jenni Nikolaenko wrote:
> 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.
Thank you! I've applied the patch, with a fix for one broken link that
was identified by our new automated broken link checking. I should
write up how to run that — I'm so behind on the documentation I want to
write. :(
I think maybe the "Working with patches" section should also go under
"Contributing", what do you think?
I'll update /contributing.html and /participating.html when I get a
chance.
Thanks for your continued contributions!
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2023-01-20 17:32 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-01-19 15:43 [PATCH] Documentation: add contributing information Jenni Nikolaenko
2023-01-20 17:28 ` Alyssa Ross
2023-01-20 17:32 ` Alyssa Ross
Code repositories for project(s) associated with this public inbox
https://spectrum-os.org/git/crosvm
https://spectrum-os.org/git/doc
https://spectrum-os.org/git/mktuntap
https://spectrum-os.org/git/nixpkgs
https://spectrum-os.org/git/spectrum
https://spectrum-os.org/git/ucspi-vsock
https://spectrum-os.org/git/www
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).