diff --git a/docs/community/contribute/app-development.md b/docs/community/contribute/app-development.md new file mode 100644 index 00000000..ccba290c --- /dev/null +++ b/docs/community/contribute/app-development.md @@ -0,0 +1,34 @@ +(contribute-to-app-development)= +# Contribute to app development + +As the developers' choice of operating systems, Ubuntu provides numerous avenues for creating new software. +Developers can pursue traditional Debian package development, build universal and sandboxed Snap applications or even create Juju Charms for container orchestration. + +Contact other app developers on the Ubuntu [app development mailing list](https://lists.ubuntu.com/mailman/listinfo/Ubuntu-app-devel). + + +## Debian packages + +The majority of source packages in Ubuntu are copied unmodified from Debian; therefore the best route for getting packages into Ubuntu is through Debian. Not only will this help ensure your application is available to Ubuntu users, but to those using Debian and the many Ubuntu flavors, remixes and derivatives. Discover more about the relationship between {ref}`Ubuntu and Debian `. + +* Follow the [Debian Packaging Tutorial](https://www.debian.org/doc/manuals/packaging-tutorial/) +* Learn the [Ubuntu New Package process](https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages) + + +## Snap applications + +Snaps are easy-to-install application packages for desktop, cloud and IoT that are secure, cross‐platform and dependency‐free. +Snaps are discoverable and installable from the [Snap Store](https://snapcraft.io/), the app store for Linux with an audience of millions. + +* Learn snapcraft by [making your first Snap](https://snapcraft.io/blog/how-to-make-your-first-snap) + + +## Juju charms + +Juju charms are deployment and service orchestration scripts that enable people to deploy services onto Ubuntu clouds on EC2, HP Cloud, and OpenStack (among others). +Since Juju charms can be written in any language, it's a good way for DevOps experts to share deployment and management scripts with the community. +Developers can share their charms on [Charmhub](https://charmhub.io/), a repository of ready-to-use charms. + +* Get started by [writing your first Juju charm](https://juju.is/docs/sdk/build-and-deploy-minimal-machine-charm) + + diff --git a/docs/community/contribute/art-and-design.md b/docs/community/contribute/art-and-design.md new file mode 100644 index 00000000..ac0110a1 --- /dev/null +++ b/docs/community/contribute/art-and-design.md @@ -0,0 +1,30 @@ +(contribute-to-art-and-design)= +# Contribute to art and design + +From its trademark "circle of friends" logo, distinct colour scheme and immediately recognizable font, Ubuntu has long had an iconic look in the open source world. +Members of the community who share a passion for art and design have a number of outlets to demonstrate their abilities. + + +## Ubuntu design and assets + +The Ubuntu design and brand is iconic and encompasses our four core values: freedom, reliability, precision and collaboration. +We encourage all to learn our design principles, contribute to our design system and discover a plethora of resources. + +* Discover our [design philosophy](https://design.ubuntu.com/brand) +* [Download art assets](https://design.ubuntu.com/resources) + + +## Community wallpaper competition + +The amazing backgrounds in Ubuntu are produced by the community. +Prior to every new release, the community team hosts a wallpaper contest where artists, photographers or anyone feeling artsy can submit their works with the top vote earners getting included in the next release of Ubuntu. + +* Take part in the latest [Ubuntu wallpaper competition](https://discourse.ubuntu.com/tag/wallpapers) + + +## Flavour art contributions + +Ubuntu Flavours often have their own distinctive style and rely on volunteers to help design their art assets. +Getting involved with Flavour art design is a great way to connect with the wider Ubuntu ecosystem and share your artistic skills with the entire community. + +* Explore the [Official Ubuntu Flavours](https://ubuntu.com/desktop/flavours) diff --git a/docs/community/contribute/contribute.md b/docs/community/contribute/contribute.md new file mode 100644 index 00000000..ea0cc7b3 --- /dev/null +++ b/docs/community/contribute/contribute.md @@ -0,0 +1,43 @@ +(contribute-to-ubuntu)= +# Contribute to Ubuntu + +```{toctree} +:maxdepth: 1 +:hidden: + +App development +Art and design +Documentation +Discourse +QA and testing +Translation +Patch Pilots +``` + +Ubuntu is most of all a community. All of the software, artwork and documentation in Ubuntu has been created, tested, used and discussed openly by people around the world. Anyone who uses Ubuntu is part of this global community, and we invite you to help shape Ubuntu to better meet your needs. To make it yours! + +Here are just a few ways to you can contribute to our community. + +{ref}`Application Development ` +: As the developers' choice of operating systems, Ubuntu provides numerous avenues for creating new software. Developers can build universal and sandboxed Snap applications, pursue traditional Debian package development, or even create Juju Charms for container orchestration. +: Do you want to create software that will be used around the world? + +{ref}`Ubuntu Development ` +: Ubuntu, like other Linux distributions, relies on a vast collection of software packages created and supported by a global community of passionate developers. There are a number of ways that you can help support its ongoing development regardless of your current skill or knowledge level. +: Are you ready to get help forge the future of Ubuntu? + +{ref}`Documentation ` +: Good software requires great documentation. Whether it's writing reference guides, updating tutorials or publishing a community blog, the Ubuntu Community is always in need of dedicated wordsmiths. +: Prepared to put pen to paper? + +{ref}`Art and Design ` +: Put your creativity to work by helping improve the look, feel and sounds of Ubuntu. Help design graphics, backgrounds and sounds for the next release. The community needs artists from all disciplines and at all skill levels. +: Do you have an eye for design? + +{ref}`Translation and Localisation ` +: Ubuntu is a global project and therefore it's important that it's available in many languages. If you're fluent in multiple languages and want to help open up the world of Ubuntu to people all over the globe, please consider joining us! +: Are you a polyglot with a passion? + +{ref}`QA and Testing ` +: Millions of people around the world rely on our software and trust that it's reliable, consistent and stable. This is only made possible by a dedicated group of testers and tinkerers who help ensure that our software is ready for general use. +: Are you excited about testing the latest and greatest? diff --git a/docs/community/contribute/discourse-documentation.md b/docs/community/contribute/discourse-documentation.md new file mode 100644 index 00000000..5e9a380c --- /dev/null +++ b/docs/community/contribute/discourse-documentation.md @@ -0,0 +1,406 @@ +(contribute-to-discourse-documentation)= +# Contribute to Discourse documentation + +Our documentation is a community effort and we warmly welcome community contributions, suggestions, fixes and constructive feedback. + +Some of our documentation is created and edited in posts on Discourse forums. +Every such documentation page has an equivalent post on a Discourse forum. +Each forum post can be accessed from documentation page by clicking the "Help improve this document in the forum" link at the bottom of the page. + +![How the "help improve this document in the forum" banner looks|540x103](help-improve-in-forum.png) + +If you feel something is unclear, wrong, or broken, please don't hesitate to leave a comment on the forum post. +You can also help us by directly editing the Discourse post. +You can also find us in the {matrix}`documentation` room on Matrix. +We always try to respond as quickly as we can. + + +(new-discourse-users)= +## New Discourse users + +Anyone can edit and contribute to our Discourse documentation, but they need to spend a little time with our Discourse forum first. + +New Discourse users are temporarily limited in their capabilities (their *Trust Level*) until they've read and participated in the forum. +New users start at Trust Level 0, but at Trust Level 1, they can create and edit Discourse posts freely. + +Trust Level 1 is attained by: + +* Entering at least 5 topics +* Reading at least 30 posts +* Spending a total of 10 minutes reading posts + +Users at Trust Level 1 can: + +* Edit wiki posts +* Use all core Discourse functions; all new user restrictions are removed +* Send private messages +* Upload images and attachments +* Flag posts to alert moderators +* Mute other users + + +(edit-a-discourse-post)= +## Edit a Discourse post + +If you {ref}`already participate ` in the community, you won't need additional permissions; pages are editable within the forum itself. +To modify any Discourse documentation topic with updated or more insightful information, click on the {guilabel}`Edit` button at the bottom of the forum post: + +![Discourse edit button](discourse-edit.png) + +The navigational structure, style, and content of our documentation follows the {ref}`Diátaxis systematic framework `. + +Documentation consistency is vital, which is why we're listing some guidelines below, but don't let this formality put you off -- just start writing and editing. +If something is inconsistent, we'll fix it. + +As [Voltaire](https://en.wikipedia.org/wiki/Voltaire) wrote, "_Perfect is the enemy of good_," and we'd rather have documentation we can fix than non-existent documentation we can't. + + +## Overview of Discourse-based documentation + +Ubuntu has many projects under its umbrella, and this table shows which documentation websites correspond to which forums. Each documentation website also has a separate guide explaining the basics of contributing to those docs. + +| Published documentation website | Contributing guide | Discourse backend | +|---|---|---| +| [MAAS docs](https://maas.io/docs) | [How to contribute](https://maas.io/docs/contributing-to-maas-documentation) | [Source](https://discourse.maas.io/c/docs/5) | +| [Mir docs](https://mir-server.io/docs) | [How to contribute](https://mir-server.io/docs/how-to-maintain-mir-documentation) | [Source](https://discourse.ubuntu.com/c/mir/docs/28) | +| [Snap docs](https://snapcraft.io/docs) | [How to contribute](https://snapcraft.io/docs/contribute-to-docs) | [Source](https://forum.snapcraft.io/c/doc/15) | + + +## Style and language + +One of our biggest challenges is accommodating an audience with a huge variation in experience, from beginners figuring out how to use an application, through developers wanting to extend it, to experts harnessing APIs and deploying it to thousands of devices. + +Consequently, we try to: +* pitch the writing appropriately for the subject +* write inclusively and assume very little prior knowledge of the reader +* link or explain phrases, acronyms and concepts that may be unfamiliar, and if unsure, err on the side of caution + +Some general tips: +* use a spell checker +* resist being too formal +* try to be concise +* verify links and examples + +We (mostly) adhere to the [Canonical style guide](https://docs.ubuntu.com/styleguide/en). + + +(discourse-diataxis)= +## Diátaxis + +Our navigational structure, style, and the content of our documentation follows the [Diátaxis](https://diataxis.fr/) systematic framework for technical documentation. +This splits documentation pages into tutorials, how-to guides, reference material and explanatory text: + +**Tutorials** +: Are lessons that accomplish specific tasks through _doing_. They help with familiarity and place users in the safe hands of an instructor. + +**How-to guides** +: Are recipes, showing users how to achieve something, helping them get something done. A _How-to guide_ has no obligation to teach. + +**Reference** +: Material is descriptive, providing facts about functionality that is isolated from what steps need to be done. + +**Explanation** +: Is discussion, helping users gain a deeper or better understanding of the tools, along with how and why they function as they do. + +For further details on our Diátaxis strategy, see [Diátaxis, a new foundation for Canonical documentation](https://ubuntu.com/blog/diataxis-a-new-foundation-for-canonical-documentation). + +Improving our documentation and applying the principles of Diátaxis are on-going tasks. +There's a lot to do, and we don't want to deter anyone from contributing to our docs. +If you don't know whether something should be a tutorial, how-to, reference or explanation, either ask on the forum or publish what you're thinking. +Changes are easy to make, and every contribution helps. + + +## Navigation menu + +The navigation menu on the published Discourse-based docs site is generated automatically from a table in that page's forum post. + +Unlike every other page in our documentation, the page hosting the navigation menu cannot be edited. +This is because we need to retain some gateway control over which pages are published and where. +A small error in the navigation table can completely break the final output and the redirects it contains could break the rendering of other pages too. + +If you think something should be added to our navigation, either leave a comment under that page's respective forum post, or the navigation page itself. + +The code that creates the navigation and publishes our documentation from Discourse [can be found here](https://github.com/canonical/canonicalwebteam.discourse). + + +## Discourse Markdown + +Documentation is written in the [Markdown](https://daringfireball.net/projects/markdown/syntax) format [supported by Discourse](https://meta.discourse.org/t/post-format-reference-documentation/19197/2). + +Mostly, you don't need to worry about the syntax. If you are unfamiliar with Markdown you can use the style toolbar in the Discourse editing window to mark the elements you need. + + +### Headings and titles + +```markdown +## Subheading within a document +### Subheading of a subheading +``` +We don't use the top-level heading (`# Heading`) because the topic title in Discourse serves this purpose. + +Headings and subheadings need to use _sentence case_, which means the first letter is typically the only one capitalised, unless the title includes names, product names or acronyms. + + +### Lists + +For an unnumbered (bullet) list, use the following syntax: + +```markdown +* This is the first item +* This is the second item + * This is a sublist +``` + +And for a numbered list, precede each item with `1.` (the numbering then becomes automatic, and it's easier to insert new items): + +```markdown +1. This is the first item +1. This is the second item + 1. This is a sublist +``` + +Unless a list item is particularly long (which should be avoided) and includes punctuation, don't end the item with a full stop. +If one item needs a full stop, add the full stop to other items too. + + +### Code blocks + +Enclose a code block with three backticks and include the *type* of code: + + ```yaml + name: gimp + version: '2.10.8' + summary: GNU Image Manipulation Program + ``` + +The most common code types are: `bash`, `yaml`, `json`, and `no-highlight`. +The last is like a miscellaneous type. +It is often used to display command output. + +You can use a command line dollar prompt (`$`) to differentiate between input and output in the same code block: + +```none +$ snap version +snap 2.36.1 +snapd 2.36.1 +series 16 +ubuntu 18.04 +kernel 4.15.0-39-generic +``` + +In sympathy with the command line, we replace `$` with `#` when running commands from root. +If you do use separate code blocks for input and output, you do not need to include a prompt symbol. + + +### Inline code + +Use a backtick to mark inline commands and other literals. +For instance, to create `$SNAP_DATA`: + +```markdown +For instance, to create `$SNAP_DATA`: +``` + + +### Angle brackets and variable names + +Angle brackets, `<>`, are typically used to show variables in example commands: + +`schema://:@
:/` + +Example variable names are acceptable if you judge that the context makes it clear enough: + +```bash +# set the working directory +WORKDIR /app +# copy the repository files to it +COPY . /app +``` + +In tutorials, provide the exact values that you want the user to use: + +`docker-compose run web django-admin startproject myapp .` + + +### Hyperlinks + +For links to internal files or external URLs, use the following format: + +```markdown +[visible text](url) +``` + +The `visible text` is what will appear in the documentation. The `url` is either the full URL of a link outside of the documentation, or (in Discourse) the topic reference number without the domain name for a page within the documentation. + +To link to `https://forum.snapcraft.io/t/snapcraft-overview/8940`, for example, you would use the following: + +```markdown +For more details, see [Snapcraft overview](/t/-/8940). +``` + + +### Anchors + +Discourse Markdown does not support anchor links to a position *within* the same page or another document. + +However, you can use standard HTML within Markdown, which means we can manually add HTML anchor elements that can be linked to. + +The [recommended way](https://meta.discourse.org/t/deep-linking-to-headings-anchors/47552) to create anchors is using heading elements with an ID. The ID needs to have `heading--` as a prefix: + +```html +

Link to me

+``` + +To create an anchor called `base-snap`, for example, enter the following into your document: + +```html +

Base snaps

+``` + +This can now be linked to with the following: + +```markdown +/t/-/8940#base-snap +``` + +Use HTML sparingly as it can make the raw text difficult to read. + + +### Notes and admonishments + +Admonishments in Discourse use BBtext markup syntax. Using `[note]` ... `[/note]` draws a box around the contained text. + +```markdown +[note type="important" status="Info"] + +An informative note. This box is dark blue. +[/note] +``` + +Which produces: + +![](note-block-with-status.png) + +You can omit the status header. + +```none +[note type="important"] + +A note without a title. +[/note] +``` + +Which produces: + +![](note-block-without-status.png) + + +#### Types of `[note]` + +The `type` parameter is optional, but recommended. +Changing the `type` parameter changes how it is presented to the reader: + +- `important` (default) +- `caution` +- `positive` +- `negative` + +The below examples are produced using type and status combinations of 'caution/Warning', 'positive/High score', and 'negative/Game over', respectively: + +#### Caution + +``` +[note type="caution" status="Warning"] +Here be dragons. + +Uses `caution` type. +[/note] +``` + +![](note-block-caution.png) + + +#### Positive + +``` +[note type="positive" status="High score"] +Great work. + +Uses `positive` type. +[/note] +``` + +![](note-block-positive.png) + + +#### Negative + +``` +[note type="negative" status="Game over"] +Please try again. + +Uses `negative` type. +[/note] +``` + +![](note-block-negative.png) + +Hyperlinks cannot be word-wrapped within admonishments. Doing so will not format the links. + + +### Comments + +Sometimes it's useful to provide information to other editors. +For that, add the comment inside a block quote that includes the `:construction:` icon. +These will be excluded from the dedicated documentation web site, but will be visible in the forum when editing. + +It may look like this: + +```markdown +[quote] +:construction: **NOTE TO EDITORS** :construction: + +This note is not visible in the dedicated documentation site. +[/quote] +``` + + +### Foldouts + +When a page contains a lot of extraneous information such as walkthroughs or reference tables, a *foldout* can be used. +This will create a collapsed header which, when clicked, will expand to display all the content below it. + +Foldout syntax in Discourse uses two sets of square brackets with an open and close details tag that acts as the title in the opening brackets: + +```markdown +[details=Manually create a network on a 10.x.x.x subnet] + +If you try to run `lxd init` on a system that is connected to a network with a `10.x.x.x` subnet, +then the final step of the Iinit* may fail with the following error: + +[/details] +``` + +The above will appear as follows: + +![](foldout.png) + + +### Images + +Most of our documentation covers command line tools, editing and developing. +However, if relevant, one can use images. +An image should be easier to understand than text, reinforce concepts being discussed in the topic, and break the monotony of words following words. + +When making images: +* do not crop your images too closely (to allow context) +* use a resolution high enough to make text legible and work with high-DPI displays +* a wide aspect ratio fits better with the width of the rendered documentation +* save with lossless compression, such as PNG for screenshots (JPG is acceptable for photos) + +Images can be dragged and dropped into the topic you're editing, or uploaded via the toolbar icon. +It can also be helpful to edit the description field of an image link after uploading: + +```markdown +![description of image](url) +``` diff --git a/docs/community/contribute/discourse-edit.png b/docs/community/contribute/discourse-edit.png new file mode 100644 index 00000000..6733c700 Binary files /dev/null and b/docs/community/contribute/discourse-edit.png differ diff --git a/docs/community/contribute/documentation.md b/docs/community/contribute/documentation.md new file mode 100644 index 00000000..8f6d46e3 --- /dev/null +++ b/docs/community/contribute/documentation.md @@ -0,0 +1,49 @@ +(contribute-to-documentation)= +# Contribute to documentation + +Good software requires great documentation and Ubuntu is always looking for community members willing to lend their writing skills to the project. +Community documentation, like the page you’re reading right now, is the product of a collaborative effort between Canonical and Ubuntu community members. + +You can join live conversations around documentation in the {matrix}`documentation` room on Matrix. + + +## Documentation practice + +At Canonical, we have embarked on a comprehensive, long-term project to transform documentation. +Our aim is to create and maintain documentation products and practice that represent a standard of excellence. +We want documentation to be the best it possibly can be. + +* Read more about Canonical's [documentation practice](https://canonical.com/documentation) +* Improve your documentation via our [Open Documentation Academy](https://documentationacademy.org/) + + +## Discourse documentation + +Some projects under our umbrella use Discourse for creating and editing documentation. +You can see the Discourse post behind these pages by clicking "Help improve this document in the forum" at the bottom of the page. +You can help improve our documentation by leaving a comment on the forum post. +If you're already active in that community's forum, you can even edit the documentation directly! + +* Learn how to {ref}`contribute-to-discourse-documentation` + + +## Community Help wiki + +The Community Help Wiki is a user-created and maintained library of Ubuntu-related documentation. +A great way to help the Ubuntu Community is to ensure that this documentation is current and accurate. +If there is missing documentation, you can also consider writing all new content. + +* Support the community by becoming an [Ubuntu Help Wiki editor](https://help.ubuntu.com/community/WikiGuide) + + +## Ubuntu Weekly Newsletter + +The Ubuntu Weekly Newsletter (UWN) is a community-operated periodical that focuses on Ubuntu-related news and events. +UWN has been producing content since 2006 and serves as a great example of community cooperation and collaboration. +Volunteers can help our community by becoming a writer, editor or link collector. + +* Get the word out by [joining the Ubuntu News Team](https://wiki.ubuntu.com/UbuntuWeeklyNewsletter) + + + + diff --git a/docs/community/contribute/foldout.png b/docs/community/contribute/foldout.png new file mode 100644 index 00000000..4e1d5bbb Binary files /dev/null and b/docs/community/contribute/foldout.png differ diff --git a/docs/community/contribute/help-improve-in-forum.png b/docs/community/contribute/help-improve-in-forum.png new file mode 100644 index 00000000..01d1f82b Binary files /dev/null and b/docs/community/contribute/help-improve-in-forum.png differ diff --git a/docs/community/contribute/note-block-caution.png b/docs/community/contribute/note-block-caution.png new file mode 100644 index 00000000..847aec3c Binary files /dev/null and b/docs/community/contribute/note-block-caution.png differ diff --git a/docs/community/contribute/note-block-negative.png b/docs/community/contribute/note-block-negative.png new file mode 100644 index 00000000..a1d220c2 Binary files /dev/null and b/docs/community/contribute/note-block-negative.png differ diff --git a/docs/community/contribute/note-block-positive.png b/docs/community/contribute/note-block-positive.png new file mode 100644 index 00000000..4dd29a19 Binary files /dev/null and b/docs/community/contribute/note-block-positive.png differ diff --git a/docs/community/contribute/note-block-with-status.png b/docs/community/contribute/note-block-with-status.png new file mode 100644 index 00000000..6ea49a8f Binary files /dev/null and b/docs/community/contribute/note-block-with-status.png differ diff --git a/docs/community/contribute/note-block-without-status.png b/docs/community/contribute/note-block-without-status.png new file mode 100644 index 00000000..2201ee37 Binary files /dev/null and b/docs/community/contribute/note-block-without-status.png differ diff --git a/docs/community/contribute/patch-pilots.md b/docs/community/contribute/patch-pilots.md new file mode 100644 index 00000000..67fa72c4 --- /dev/null +++ b/docs/community/contribute/patch-pilots.md @@ -0,0 +1,99 @@ +(patch-pilots)= +# Patch Pilots + +Welcome to the Patch Pilot Program! + +Our aim is to support contributors with their patches, package sponsoring, and other activities to improve Ubuntu. +The program is designed to make contributing to Ubuntu a welcoming and inspiring experience while fostering community knowledge and maintaining ongoing contributions. + + +## Get help from a Patch Pilot + +Are you interested in contributing patches to Ubuntu? +There are a number of ways to participate, and through this program we'd like to provide you with mentoring and support in getting your patches into Ubuntu. +You should reach out to a Patch Pilot if: + +* You have a {ref}`patch against an Ubuntu-specific package ` that you'd like to contribute. +* Your package can't go into Debian and you'd like to contribute a {ref}`new Ubuntu-specific package `. +* You'd like a new package or patch to appear in Ubuntu, but need some guidance on how to make it part of Debian. + +Patch Pilots are available in the {matrix}`devel` channel on [Matrix](https://ubuntu.com/community/communications/matrix) and will be monitoring bugs with patches on Launchpad. +The current Pilot is noted in the channel topic. +If you'd like to plan ahead, see the [Ubuntu Patch Pilots](https://calendar.google.com/calendar/embed?showPrint=0&showCalendars=0&mode=WEEK&src=Y184ZWRhZjk2OTllYWFmMWFmMmNjYTY2ZTYyOGZkNDEwODQ2ZTkwMjcwNmQ2YTMzMTU1OTNmODhiOTk0ZTZlOWE2QGdyb3VwLmNhbGVuZGFyLmdvb2dsZS5jb20&color=%23F4511E) calendar. + + +## Being a Patch Pilot + +As a Patch Pilot, you will be a primary contact in supporting the community towards Ubuntu development. +It is the development equivalent of being "on call" in the site reliability engineering (SRE) world. + + +### Welcoming the community + +We value the support from Ubuntu community members and strive to create a positive and engaging atmosphere. +To achieve this, we identify contributors with potential to grow as advocates or future Patch Pilots while ensuring that all contributors are treated respectfully, provided with learning resources, and supported throughout their journey. + +Some techniques to foster engagement include: + +* Thanking contributors for their contributions and time commitment +* Offering encouragement and highlighting their strengths +* Informing contributors of their progress and setting expectations + + +### Reasonable contributions + +Please do your best to accept contributions in any reasonable form. +Remember, every contributor has their own unique journey and way of giving. +All we ask is that the submitted contribution is functional (e.g. patch applies), builds correctly, and has been tested. +If you're ever uncertain, here are some examples of where you as a Patch Pilot can support contributors: + +* Patch against the wrong git branch +* Needs a quilt patch rather than a change directly to upstream sources + +If there are opportunities to improve tooling for uncommon types of contributions, please discuss on the [`ubuntu-devel` mailing list](https://lists.ubuntu.com/archives/ubuntu-devel/). +You are welcome to point contributors to guides on preferred ways to contribute for their future patches, which helps them learn more about our ecosystem. + + +### Activities breakdown + +Sponsoring queue +: The primary focus is the [general sponsoring queue](http://sponsoring-reports.ubuntu.com/general.html). The Patch Piloting program is designed to support community contributors to Ubuntu. When reviewing changes and sponsoring uploads, keep the following in mind: +: * Prioritize community contributions before contributions by Canonical employees +: * Prioritize items waiting the longest +: * Manage expectations by informing contributors about expected feedback times +: * Avoid moving goal posts and provide thorough explanations when abandoning long-pending changes + + +Availability on Matrix +: During your Piloting session, you are the primary representative for inquiries in {matrix}`devel` on Matrix. Address questions about contribution processes, technical patch issues, or repository support while fostering encouraging conversations about patch contributions. + +: When you begin your session, please write `@pilot in` in {matrix}`devel`, which will add a note to the topic that you are the current Patch Pilot. Once your session is finished, use `@pilot out` to remove yourself. + +: When conversing on other platforms such as Launchpad, you are also welcome to point patch authors to {matrix}`devel` and this program to continue discussions. If contributors reach out to you outside of your session, feel free to refer them to the current Patch Pilot. + + +Operation Cleansweep +: There is a growing number of [open bugs with patches on them](https://bugs.launchpad.net/ubuntu/+bugs?field.subscriber=ubuntu-reviewers&field.tag=-patch-needswork%20-patch-forwarded-upstream%20-patch-forwarded-debian%20-patch-accepted-upstream%20-patch-accepted-debian%20-patch-rejected-upstream%20-patch-rejected-debian%20-patch-rejected&field.tags_combinator=ALL). Following the [Review Guide](https://wiki.ubuntu.com/ReviewersTeam/ReviewGuide#Workflow), you can help make sure community members have the support they need to get their patches into Ubuntu. Contributors might occasionally need clarification on the guidelines, and we're here to provide support and guidance. + + +Developer documentation +: There's extensive documentation on Ubuntu Development in these Ubuntu Project docs. Even small changes can greatly improve the documentation, ensuring it remains updated and effective. This is a great opportunity to improve on that, which will decrease recurring questions over time. + +: If you are unsure about the scope of your changes and would like some guidance, please reach out to {matrix}`documentation`. However, don't be afraid to make more extensive changes. A large amount of outdated documentation can cause more harm than a small amount of available up-to-date information. + + +### Program logistics + +Communication and handoff +: The primary channel to exchange information as a Patch Pilot is {matrix}`devel`. Please avoid private messages unless needed, as this helps keep the community in the loop and provides context for the next Patch Pilot. + +: After completing your work, provide a helpful handoff to the next Patch Pilot, including context and additional instructions as needed. Handoff should be posted in the [Patch Pilot handoff thread](https://discourse.ubuntu.com/t/patch-pilot-hand-off-25-10/60037) for the 25.10 cycle. + + +Requirements +: To be a Patch Pilot, you need to be able to upload packages to Ubuntu. There are a number of ways to get there, but the first step is to become an {ref}`Ubuntu Developer `. + +: When you begin Patch Piloting, ask to be added to the [Ubuntu Sponsors](https://launchpad.net/~ubuntu-sponsors/) group as well. If you're not currently an Ubuntu Developer but wish to become one, {ref}`find out how to apply `. + +Time commitment +: Our rotation schedule presently results in one pilot session every 3 weeks. Each session lasts up to 4 hours, designed to offer uninterrupted time for contributors to ask questions. However, if you're a community member interested in joining and have concerns about the session duration, please reach out. We're open to feedback and discussions about possible adjustments to make participation feasible for you. diff --git a/docs/community/contribute/qa-and-testing.md b/docs/community/contribute/qa-and-testing.md new file mode 100644 index 00000000..d8481a20 --- /dev/null +++ b/docs/community/contribute/qa-and-testing.md @@ -0,0 +1,35 @@ +(contribute-to-qa-and-testing)= +# Contribute to QA and testing + +Ubuntu, like any other software, needs good testers. +You can contribute to Ubuntu simply by running the latest version and reporting software issues -- we call them bugs -- and helping to manage those bugs until they are fixed. +For those feeling more adventurous, the community is always looking for people willing to test out new pre-release versions of Ubuntu. + + +## Join the QA Team + +A great way to get started helping with Ubuntu Quality is to join the QA Team and subscribe to their communication channels. +These initial steps will help you get acquainted with current QA-related issues and keep you informed of upcoming tasks and initiatives. + +* Help improve Ubuntu by joining the [Ubuntu Quality Team](https://launchpad.net/~ubuntu-testing) + + +## Bug reporting + +While using Ubuntu, or its many software packages, you may experience a software issue. +There are many reasons why this happens and not all issues constitute a bug. +Issues that are *not* the result of a glitch or a simple user mistake may need a bug report to be filed. +The Ubuntu community uses Launchpad as its primary bug reporting and tracking system. + +* Discover the keys to [successful bug reporting](https://ubuntu.com/blog/the-keys-to-successful-bug-reporting) + + +## Ubuntu pre-release testing + +New Ubuntu versions are released every 6 months, which means that prior to their release it is critical to identify and address major bugs. +This is where community testers serve as an invaluable resource. +Helping test Ubuntu and its numerous Flavors is a fun and easy way to give back to the community. + +* Join in the testing conversations on the [Ubuntu Testers Telegram channel](https://t.me/UbuntuTesters) + +* Test the latest Ubuntu builds on the [Testing Tracker](http://iso.qa.ubuntu.com/) diff --git a/docs/community/contribute/translation.md b/docs/community/contribute/translation.md new file mode 100644 index 00000000..18d71dac --- /dev/null +++ b/docs/community/contribute/translation.md @@ -0,0 +1,23 @@ +(contribute-to-translation)= +# Contribute to translation + +Ubuntu is a global project and it's important that Ubuntu is available in many languages. +If you are fluent in multiple languages and want to help open up the world of Ubuntu to people all over the globe, consider becoming a community translator. + + +## Translating with Launchpad + +Using Launchpad, you can translate free software projects and distribution packages into your own language. +All you need is a Launchpad account and a web browser. +There's no special software, and in most cases you don't need to join a team to get started. + +* Get started by reading the [Translation Quickstart Guide](https://wiki.ubuntu.com/Translations/QuickStartGuide) + + +## Join a Translation Team + +Once you understand the translation process and want to further your involvement, you can join a Translation Team. +These groups of volunteers work together to help localize Ubuntu for their respective languages. +Each team has its own set of goals, rules and processes that you will need to follow if you choose to join. + +* Find a [Translation Team for your language](https://translations.launchpad.net/+groups/ubuntu-translators) diff --git a/docs/community/index.md b/docs/community/index.md index 9fcdafb5..2b731bfb 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -7,4 +7,5 @@ ethos/index governance/index +contribute/contribute ``` diff --git a/docs/community/local/index.md b/docs/community/local/index.md new file mode 100644 index 00000000..3e5cce43 --- /dev/null +++ b/docs/community/local/index.md @@ -0,0 +1,41 @@ +(local-communities)= +# Ubuntu Local Communities + +```{toctree} +:maxdepth: 1 +:hidden: + +lc-create +lc-handover +lc-faq +``` + +![loco-map|450x228](loco-map.png) + +Ubuntu Local Communities, often shortened to LoCos, are regional teams that help advocate, promote, translate, develop and otherwise improve Ubuntu. + +With the incredible success of Ubuntu around the world, the Ubuntu Local Communities program was formed to help Ubuntu fans and enthusiasts work together. Our worldwide network of LoCo teams are an important staple in the Ubuntu ecosystem and provide a strong backbone to our already vast and extensive Ubuntu community. + + +## What are the perks of being in an Ubuntu Local Community? + +* Network with other Ubuntu enthusiasts in your region. +* Access to exclusive Ubuntu {spellexception}`Merch` Packs and swag. +* Future event sponsorship opportunities. +* Participation may lead to future {ref}`ubuntu-membership`. +* Help spread the mission of free and open source software around the world! + + +## How to join an Ubuntu Local Community + +Becoming part of an Ubuntu Local Community is a great way to meet other passionate Ubuntu enthusiasts in your community. Find a team in your area to join by checking out the [Ubuntu Local Community Teams](https://ubuntu.com/community/locos/join) Directory. + + +## How to create an Ubuntu Local Community + +Can’t find a team in your area? You may want to consider starting one! Learn how you can {ref}`Create an Ubuntu Local Community `. + + +## Join in the Ubuntu Local Community conversation + +Do you have other Ubuntu Local Community related questions or want to help shape the future of the program? Engage with other LoCo leaders and advocates in the [Ubuntu LoCo Discourse](https://discourse.ubuntu.com/c/locos/129). diff --git a/docs/community/local/lc-create.md b/docs/community/local/lc-create.md new file mode 100644 index 00000000..c0f16624 --- /dev/null +++ b/docs/community/local/lc-create.md @@ -0,0 +1,115 @@ +(lc-create)= +# Starting a Local Community + +Welcome! We're thrilled that you're interested in starting an Ubuntu Local Community. +Starting a new Local Community may sound difficult, but all it takes is a passion for Ubuntu and a desire to share it with others around you. +This guide is meant to help you get a Local Community up and running in your region with a number of useful tools and resources. + + +## Setting up communications + +Communication is key when it comes to running a Local Community. +Canonical and the Ubuntu community provide a number of tools and services to help our Local Community leaders do what they do best. + + +### Ubuntu Community Portal + +[The Ubuntu Community Portal](https://ubuntu.com/community) is the gateway into the Ubuntu Community and aggregates events, Local Communities, news, documentation like this and more from around the Ubuntu ecosystem. +The majority of the content from the portal is dynamically sourced from our Discourse server which you'll learn how to tap into in the next section. + + +### Ubuntu Discourse + +[The Ubuntu Discourse](https://discourse.ubuntu.com), which we refer to as the 'Community Hub', is a powerful forum platform where Ubuntu community members come together to collaborate, discuss projects and support one another. +Content on the Discourse is broken down into categories, including one for Ubuntu Local Communities. + +1. [Sign up for a Discourse account](https://discourse.ubuntu.com/auth/saml?signup=true) (and Ubuntu One account if you haven't already). +2. Once you're logged in, head over to The [Ubuntu Local Communities section](https://discourse.ubuntu.com/c/locos/) and see if a category already exists for your region. + If not, you can request one by [filling out this form](https://docs.google.com/forms/d/e/1FAIpQLSf7auchvVzpkH_cQdUFiiRcyGHtrSrGG0GmeQXaKkDhXVpsmw/viewform?usp=sharing&ouid=101065845149003260161). + + +### Ubuntu Matrix server + +Local communities may also want a means of instant communication. +The Ubuntu community, along with a number of other open source communities, have opted for the open source Matrix protocol for their synchronous communication needs. +To get started using Matrix check out the following guides: + +1. [Getting Started with Matrix](https://ubuntu.com/community/docs/communications/matrix/onboarding) -- Will show you how to install and use the Element App, getting your personal Matrix account setup, and how to connect to the Ubuntu Matrix server. +2. [Creating a public room](https://ubuntu.com/community/docs/communications/matrix/room-creation-public) -- Will walk you through creating a public room for your local community to use and converse on. + + +## Create and hosting events + +Events are where your community comes to life. +They can be online or in person, formal or casual. + + +### Choose a venue + +Perhaps the biggest challenge when it comes to hosting a local community meetup is where to actually meetup! +Generally, it's a good idea to find a place that's both affordable and accessible. +Some excellent options include: + +* Universities and trade schools +* Non-profits and tech unions +* Community centers +* Co-working spaces +* A quiet corner of a pub or restaurant + +Be sure to check with the owners of each space to ensure they can accommodate your crowd size, technology offerings (wifi, projector), accessibility needs, catering desires, and any other important personnel considerations. + +Also, if you aren't quite ready for an in-person gathering, consider setting up an online meetup! +We are a technology focused community after all. + + +### Get the word out + +You want folks to be able to find your exciting event and learn how they can participate. +To get your event listed on the Ubuntu Community Portal, follow this [Creating an Event Topic](https://discourse.ubuntu.com/t/creating-an-event-topic/42013) guide. +Once your event is created and listed on the Community Portal, don't forget to share it on social media with all the appropriate **`#ubuntu`** tags. + + +### Share your successes + +After you've hosted or taken part in an event, be sure to let the community hear all about it. +Consider posting a topic on the Ubuntu Discourse, either in the [Events section](https://discourse.ubuntu.com/c/events/) or under your Local Community, with a recap of everything you did, learned and experienced. +Don't forget to use the **`#event-report`** tag and add any pictures or videos you may have snapped while you were there! + + +## Leveling up + +(loco-verification)= +### Team verification + +Once you've successfully held a few events and have demonstrated a strong degree of organization, you can request verification from the Ubuntu Local Community Council. +Gaining verified status will allow you to request Ubuntu swag, funds for traveling and possible invitations to future Ubuntu events. +Note that the council will look at activity on the Ubuntu Discourse (event reports, general conversations) to determine if your team is eligible, so it's important to be active on that platform. + +To request verification for your local community, post a topic with the title "Verification Request - LOCAL COMMUNITY NAME" in the [LoCo Support category](https://discourse.ubuntu.com/c/locos/loco-support/156) on Discourse. + + +### UbuCons + +Ubuntu Conferences, or UbuCons for short, are organized gatherings of Ubuntu and open source enthusiasts that take place all over the world. +These volunteer run events are typically organized by a Local Community or multiple communities collaborating together. +Any Local Community can host an UbuCon, but only those with significant organization and precision may be eligible for Canonical sponsorship. + +You can see previous and upcoming UbuCon events by visiting the [official UbuCon site](https://ubucon.org). + + +## Other tips and best practices + +### Leadership + +Ubuntu Local Communities are meant to be collaborative and consensus-led groups. +While many Local Communities opt to elect team leaders, no one person should have complete control over a given region. +As Local Community teams grow and aim to become more organized, they may consider electing additional leaders and specific positions like treasurer, secretary or even social media coordinator. +Every team is different and it's important to do what works best for your community. + + +### Conflict resolution + +Members of Local Communities, like all those who participate in our community, are bound by the {ref}`Ubuntu Code of Conduct `. +This simple set of guiding principles helps ensure our community remains constructive, collaborative, helpful and kind. +If you feel someone is in violation of the Code of Conduct, please contact the [Ubuntu Local Community Council](mailto:loco-council@lists.ubuntu.com) or the [Ubuntu Community Council](mailto:community-council@lists.ubuntu.com). + diff --git a/docs/community/local/lc-faq.md b/docs/community/local/lc-faq.md new file mode 100644 index 00000000..020ba4d2 --- /dev/null +++ b/docs/community/local/lc-faq.md @@ -0,0 +1,36 @@ +(lc-faq)= +# Local Community FAQ + +## Where does the term LoCo come from? + +LoCo is shorthand for **Lo**cal **Co**mmunities. +There are millions of Ubuntu users all over the world. +LoCos provide an opportunity for those users to gather together in their respective regions to network, host meetups and advocate for Ubuntu and Open Source. + + +## What is Ubuntu Local Community verification? + +Ubuntu LoCo teams who have demonstrated a sustained track record and a commitment to the values of the Ubuntu Community can apply for verification. +Verified teams have access to various perks and benefits within the greater Ubuntu community. + +Learn more about the {ref}`Ubuntu Local Community Verification ` process. + + +## Who can I reach out to for help with my Local Community? + +If you are experiencing a problem or have a question about the LoCos program, you can reach out to the [LoCo Council](mailto:loco-council@lists.ubuntu.com). +The LoCo Council is the governing body that makes decisions on resource allocation, deals with conflict resolution and makes decisions about where the project should move forward. + +For general questions about the Ubuntu Local Community program, you may also create a topic in the [LoCo Support category](https://discourse.ubuntu.com/c/locos/loco-support/156) of the Ubuntu Discourse. + + +## The LoCo in my region is inactive, how can I restart it? + +If you’re interested in taking over a LoCo team that has been inactive for a sustained period (over 1 year) please send an email to the LoCo council with the subject "Request change of LoCo Ownership" to the [LoCo Council](mailto:loco-council@lists.ubuntu.com) including: + +* Your name and link to your Launchpad profile +* The LoCo team you wish to take ownership of +* A brief explanation of why you would like to assume ownership of the LoCo + +If the Council confirms your request, you will be given access to that LoCo and notified via email. + diff --git a/docs/community/local/lc-handover.md b/docs/community/local/lc-handover.md new file mode 100644 index 00000000..b072043b --- /dev/null +++ b/docs/community/local/lc-handover.md @@ -0,0 +1,95 @@ +(lc-handover)= +# Local Community handovers + +```{admonition} Process document +:class: note + +Approved by [loco-council](https://discourse.ubuntu.com/g/loco-council) with vote on 28 August 2024. [Vote details](https://discourse.ubuntu.com/t/vote-approving-proposed-loco-handover-process/47479/7). +``` + +The handover of a Local Community leadership can be a request from the current leaders or by prospective leaders willing to take over the LoCo. +If the request comes from a current leader of the LoCo, the "LoCo leadership check" can be skipped. +However, if the request comes from a prospective leader, the following needs to be done. + + +## Submitting a Handover request + +If current leaders or prospective leaders want to request LoCo handover, they need to submit a request by creating a topic on Discourse [LoCo Support](https://discourse.ubuntu.com/c/locos/loco-support/156) category [with this template](https://discourse.ubuntu.com/t/draft-loco-handover-request-template/47150). + + +## LoCo leadership check + +The LoCo Council will to try to contact the current leadership of the LoCo using all means of communication found on the Launchpad profiles of current leaders, including but not limited to: + +- Email +- Discourse +- Chat(IRC, Matrix, etc.) +- "Contact this user" button on Launchpad profile +- If all the above do not work, other ways of communication suggested from prospective leaders + +The window of 15 days will be given to get a reply in at least one of the means above. +If this period is past and no reply was received, then up to 2 more rounds of "trying contact" are made. +After this period, the LoCo leadership is considered unreachable by the LoCo Council. + +If a response from current LoCo leaders is received, then we need to confirm the following from the current leaders: + +* If they are currently running their LoCo actively or not. + If LoCo Council can confirm any of the following, the current leaders will be considered as active: + + * LoCo with current leaders have either done verification or re-verification in the last 2 years from the day LoCo Council received handover request. + + * Current leaders have done several activities in the last 2 years and they also have detailed and solid plans for future activities. + + * For their recent activities, current leaders need to share proof such as photos, reports on Discourse, and it must be easily accessible publicly. + + * For future activity plans, current leaders will need to provide a formal write up and it should sound feasible with consideration of their situation and backgrounds. + +* Whether they agree to the handover process or not. + +If current leaders agree to the handover: + +* If current leaders are running their LoCo actively, LoCo Council will ask them to handle it by themselves (besides those tasks that could be facilitated by the LoCo Council). + +* If current leaders are inactive, LoCo Council will take care the next steps of the handover process. + +If current leaders disagree: + +* If current leaders are running their LoCo actively, the process will be halted without any handover. + +* If current leaders are inactive, LoCo Council will proceed with next steps and if LoCo Council decides it's better to handover to prospective leaders, handover will be made only in that case. + +If the LoCo is considered inactive and not reachable, we'll need to check how prospective leaders are currently recognized in their region. + +To do this, LoCo Council will need to gather following information first: + +* Information about prospective leaders: + + * Names, biography in 2 or 3 sentences + + * URL of their Ubuntu Discourse and Launchpad Profiles -- with their latest and reachable contact information such as email, IRC and Matrix filled in on their profile. + +* Their recent 6 months activity reports with links or attachments (such as blog posts, event reports, photos and more) and future activity plans from prospective leaders. + +* Endorsements from members or people who have been involved with the LoCo. + +Based on information gathered, if the LoCo Council can confirm that they have already organized a number of activities and have enough people who agree that prospective leaders should lead the LoCo, LoCo Council can proceed with next steps of handover process. + + +## Identify new leadership + +Once the LoCo Council makes a decision to proceed with handover, LoCo council will need to check the list of prospective leaders once again -- this time along with their roles for communicating with LoCo Council. +Such as LoCo contact, who will be the person the LoCo Council can contact if needed, and also one or two backup contact persons in case the LoCo council were not able to communicate with the LoCo's main contact person. + + +## Identify resources to be handed over to prospective leaders + +If any of the following resources for the LoCo exists, and in case the current leaders can't handle the resource handover, the LoCo Council will also assist in the handover to prospective leaders. +In case such resources do not exist yet, prospective leaders can ask the LoCo Council to facilitate the set up of the resources required. + +- Admin access of real-time chat channels: IRC (Libera.chat) and Matrix (ubuntu.com) +- LoCo mailing list +- Discourse LoCo category +- Domain (DNS) access (ubuntu-**.org) +- LoCo Team on Launchpad + +Other resources such as social media accounts, websites and forums that were set up by the LoCo themselves needs to be handed over by LoCo leaders themselves, as those are not accessible by the LoCo Council. diff --git a/docs/community/local/loco-map.png b/docs/community/local/loco-map.png new file mode 100644 index 00000000..2698c191 Binary files /dev/null and b/docs/community/local/loco-map.png differ diff --git a/docs/who-makes-ubuntu/index.md b/docs/who-makes-ubuntu/index.md index 92c90f7c..74c30ba4 100644 --- a/docs/who-makes-ubuntu/index.md +++ b/docs/who-makes-ubuntu/index.md @@ -4,8 +4,7 @@ ## Councils and Boards -Explanation of the Councils and Boards, their responsibilities and remit, and -how one becomes a member. +Explanation of the Councils and Boards, their responsibilities and remit, and how one becomes a member. ```{toctree} :maxdepth: 1 @@ -16,10 +15,8 @@ councils/index ## Roles -Explains the various roles one can take on when you become a member of the -community, and the permissions and responsibilities each role has. -Includes how to contact each group, their standard operating procedures (SOPs) -and any service level agreements/objectives (SLAs/SLOs). +Explains the various roles one can take on when you become a member of the community, and the permissions and responsibilities each role has. +Includes how to contact each group, their standard operating procedures (SOPs) and any service level agreements/objectives (SLAs/SLOs). ```{toctree} :maxdepth: 1 @@ -28,9 +25,9 @@ roles/index ``` -## Joining a role +## Ubuntu Developers -Explanation of the various pathways, expectations, and how to apply for a role. +Explanation of the various pathways to upload rights, expectations, and how to apply for an uploader role. ```{toctree} :maxdepth: 1 @@ -38,16 +35,18 @@ Explanation of the various pathways, expectations, and how to apply for a role. developers/dmb-index ``` + ## Ubuntu Membership -About Ubuntu Membership, the benefits and responsibilities, and how to become -an Ubuntu Member. +About Ubuntu Membership, the benefits and responsibilities, and how to become an Ubuntu Member. ```{toctree} :maxdepth: 1 /community/membership/index ``` + + ## Specialist teams For specific, specialist teams on Launchpad. @@ -57,3 +56,13 @@ For specific, specialist teams on Launchpad. specialist-teams/index ``` + + +## Local Communities + +```{toctree} +:maxdepth: 1 + +/community/local/index +``` +