From Fedora Project Wiki

(s/websites/legal for any documentation on problematic software)
(Document that the edit summary field doesn't appear until the user clicks the Publish button, so users do not worry that clicking the button will publish without an edit summary.)
 
(2 intermediate revisions by one other user not shown)
Line 36: Line 36:
Do not add any information that violates the law.  Remember that the Fedora Project is an entity in the United States, and is governed by its laws.  Avoid linking or adding information about software that is not free and open source or that is legally encumbered.  If you think you have a special exception, bring it to the attention of the [[Legal]] team for discussion.  See the [[ForbiddenItems]] page for examples of items that should be avoided.
Do not add any information that violates the law.  Remember that the Fedora Project is an entity in the United States, and is governed by its laws.  Avoid linking or adding information about software that is not free and open source or that is legally encumbered.  If you think you have a special exception, bring it to the attention of the [[Legal]] team for discussion.  See the [[ForbiddenItems]] page for examples of items that should be avoided.


Bring questions to the [[Websites]] team for discussion.  If needed, they can get the official word.
Bring questions to the [[Legal]] team for discussion.  If needed, they can get the official word.


=== Be careful when editing key guides or pages ===
=== Be careful when editing key guides or pages ===
Line 42: Line 42:
Large and important guides, such as the [[Packaging/Guidelines| Packaging Guidelines]] , are generally managed by a specific individual or small group.  It is best to work with them when you feel that changes are needed.
Large and important guides, such as the [[Packaging/Guidelines| Packaging Guidelines]] , are generally managed by a specific individual or small group.  It is best to work with them when you feel that changes are needed.


Important pages, like the FedoraMain or [[Distribution/Download|  Download]]  pages, are the first thing that many visitors see.  Changes to such pages should generally be left to experienced contributors.  If you feel that something on such a page should be altered, bring the issue to the [[Websites]] team for discussion.
Important pages, like the FedoraMain or [[Distribution/Download|  Download]]  pages, are the first thing that many visitors see.  Changes to such pages should generally be left to experienced contributors.  If you feel that something on such a page should be altered, bring the issue to the [[Legal]] team for discussion.


=== Do not edit pages just to edit pages ===
=== Do not edit pages just to edit pages ===
Line 98: Line 98:
=== Summarize your changes (aka commit log message) -- this is the rule ===
=== Summarize your changes (aka commit log message) -- this is the rule ===


We all need to be able to quickly glance at a change and know the substance of it.  A full diff is not always available. You must supply a summary of your change (''Summary:'' field when editing). This is akin to a changelog message.  Explain what you did and why, as well as other useful links and details.
We all need to be able to quickly glance at a change and know the substance of it.  A full diff is not always available. You must supply a summary of your change (''Summary:'' field when editing). ('''Note:''' As of 2018-07-13, this field does not appear until you click the "Publish" button.) This is akin to a changelog message.  Explain what you did and why, as well as other useful links and details.


If you choose to not put in a summary, it should be the rare exception.  One reason is when doing a minor edit.  In that case, be sure to check ''This is a minor edit'' when saving.
If you choose to not put in a summary, it should be the rare exception.  One reason is when doing a minor edit.  In that case, be sure to check ''This is a minor edit'' when saving.

Latest revision as of 20:00, 13 July 2018

This page sets out general guidelines for the Fedora Project wiki.

There are a few simple points you should follow as you make changes to the wiki. Below are some examples. In general, be courteous and use common sense. Defying these guidelines and causing problems are a good way to get your edit privileges revoked. If you have questions, you can ask on #fedora-websites on freenode.

Introduce yourself

Before you start editing any page, kindly introduce yourself by adding your information to your wiki page. After you have registered your name in the wiki, you automatically have a personal wiki page located at http://fedoraproject.org/wiki/User:<username>, where <username> is replaced by your Fedora Account System account name. You can also easily get to your wiki page by clicking your username in the top right-hand corner of each page of the wiki.

For examples, take a look at some wiki pages of our contributors.

Old user pages from Moin
We do ask that you move your old FirstnameLastname style pages from Moin to the new MediaWiki format. If you just joined the Fedora Project and read that you should use the FirstnameLastname format, please contact Ian and let him know where you saw this.

Make sure you mention at least your email address and, if you are on IRC often, your IRC nick and channels you are often in.

Always watch pages that you create or edit

It is important that you follow changes to pages you create or edit, so you can coordinate with others working in the wiki content. Wiki editors usually add notes to the pages to convey information to each other as part of working together, and it helps to keep track of these changes.

You can find the watch link in the tab bar at the top of a page when you are logged in.

Be Bold

Be bold while editing changes. Wiki changes are tracked and can be reverted when necessary. This doesn't mean you should be reckless, especially when making large changes to key documents.

For more information on being bold, take a look at the be bold editing guideline on Wikipedia.

Avoid unnecessary edits of pages that discuss legal issues

These pages have been carefully written, and the words chosen carefully. When changing these documents, it is usually best to ask for review before applying changes. You can contact the Fedora Advisory Board for assistance.

Do not provide details of forbidden items

Do not add any information that violates the law. Remember that the Fedora Project is an entity in the United States, and is governed by its laws. Avoid linking or adding information about software that is not free and open source or that is legally encumbered. If you think you have a special exception, bring it to the attention of the Legal team for discussion. See the ForbiddenItems page for examples of items that should be avoided.

Bring questions to the Legal team for discussion. If needed, they can get the official word.

Be careful when editing key guides or pages

Large and important guides, such as the Packaging Guidelines , are generally managed by a specific individual or small group. It is best to work with them when you feel that changes are needed.

Important pages, like the FedoraMain or Download pages, are the first thing that many visitors see. Changes to such pages should generally be left to experienced contributors. If you feel that something on such a page should be altered, bring the issue to the Legal team for discussion.

Do not edit pages just to edit pages

Senseless edits should be avoided. Making an alteration to a page just to put your name in the edit log is unacceptable. There are plenty of pages (most of them, in fact) that have real errors that can be corrected. Instead of making pointless edits, such as removing or adding whitespace or changing links from fedoraproject.org to www.fedoraproject.org (the former is preferred), try finding errors in spelling, grammar or punctuation that can be corrected. Also, when correcting a small error, mark "This is a minor edit" using the appropriate checkbox before you save it.

Avoid renaming pages or moving content without coordination

Wiki pages are generally referred to and linked to from various other locations. It is important that you coordinate with the appropriate groups before moving content or renaming existing pages. It would be better to avoid doing that without strong rationale. If you wish to discuss moving a particular item, bring your questions to the Websites team.

Deleting Pages

Wiki pages that are no longer needed can be tagged for deletion by adding {{Delete|Reason}} to the beginning of the page, this gives Wiki Administrators the ability to ensure that important or archivable content is not lost.

Follow the ideals that Fedora holds important

For example, try to remain desktop-neutral and user-friendly, especially for non-technical users who are new to Linux and to Fedora. Users may use GNOME, KDE, the console, or some other environment. Try to keep that in mind when writing instructions. Make sure that Fedora's devotion to free and open source technology is also represented properly.

Sign your attachments

When you attach a file to a wiki page, you should create a detached signature with your GPG key. Some file formats, such as RPM packages, support GPG keys, in which case you do not need to create a detached signature -- a signature in the file will be enough. A detached signature can be attached to the page alongside the original attachment, or can be included in the page itself.

GPG signatures allow others who download your file to verify that it came from you and has not been modified or corrupted. They do not violate your privacy in any way, they simply allow others to have confidence in the origin of your files.

Images and simple documents are safe to leave without a signature, but there would be no harm in adding one anyway to verify that you were the author.

If you do not have a GPG key or want to learn more, see the Cryptography page.

Review your changes for errors

Whether you are a skilled writer, or your English skills are not strong, invite someone else to review. Well-written documents are important to Fedora's image. Even the best writers are prone to typos or other errors. Take a moment to review your changes to catch small errors. Use the Show preview button when editing a page to check your syntax.

Fedora is a community

When writing content, for the wiki or elsewhere, remember that Fedora is a community. We operate as one, unified group, moving towards common goals. We do not need to distinguish one group or class against another. For example, there is no need to distinguish between contributors who work for Red Hat and those who do not. All contributors are part of the same community. There will be cases where classification is necessary, but it can be avoided otherwise.

If you aren't sure about something, feel free to ask

Other community members will be happy to assist you. The #fedora-websites channel on freenode is the perfect place to discuss the wiki or other Fedora websites.

Watch your pages, and other ones, too

Two details make a Wiki successful as an open content collaboration tool. First is being able to watch content you are responsible for, to make certain it stays true to its mission. Second is being able to watch other content develop, grow, and occasionally need your help.

To watch any page on the wiki, after logging in, click the watch link in the tab bar at the top of a page. It should change to unwatch after it has finished. If a page has unwatch at the top, you are already watching that page. You can click unwatch to unwatch a page.

To receive emails for every edit, go to my preferences (at the top of the page by your name) and make sure to check the appropriate boxes in the User profile tab, under Email.

Using Special:Watchlist

Special:Watchlist (available by clicking my watchlist at the top of each page when you are logged in) displays pages you are currently watching. For more information on how to use this special page, please the manual page at Mediawiki.org.

We are now maintaining a stand-alone Watchlist_How-To to help Fedora contributors with specific suggestions and tools.

Summarize your changes (aka commit log message) -- this is the rule

We all need to be able to quickly glance at a change and know the substance of it. A full diff is not always available. You must supply a summary of your change (Summary: field when editing). (Note: As of 2018-07-13, this field does not appear until you click the "Publish" button.) This is akin to a changelog message. Explain what you did and why, as well as other useful links and details.

If you choose to not put in a summary, it should be the rare exception. One reason is when doing a minor edit. In that case, be sure to check This is a minor edit when saving.