[[practicalities]]
=== Practicalities of Contributing

[role="summary"]
Quick start guides and details for contributors to the project_name.

// See note in guidelines.txt about variable substitutions.

Thank you for your desire to help us create a great project_name! The sections
below contain information you'll need, in order to contribute your time and
skills to this project. Start with:

* <<practicalities-writing-phase>> if you want to write the first draft of a
topic

* <<practicalities-editing-by-task>> if you want to do some editing

* <<practicalities-translating>> if you want to help translating it to a
different language


[[practicalities-writing-phase]]
==== Quick start guide - writing tasks

Here is an abbreviated guide to writing the first draft of a topic for the
project_name project.

project_special_link_instructions

*Note: If you contribute your writing to this project, you agree that it will
be licensed with the project_license license. See <<copyright-license>> for
details.*

. *Find a topic* that you can write within about two weeks, and locate its
issue. See <<practicalities-find-topic>> for details on how to do this.

. *Claim the task* by assigning the issue to yourself. See
<<practicalities-task-claim>> for details.

. *Write* your topic:
  * See <<practicalities-editing>> for details on how to find and edit files.
  * See <<formatting>> for details on how to format the text in files.
  * See <<practicalities-composing>> for suggestions on deciding what to
    write.
  * See <<good-writing>> and <<guidelines-writing>> for guidelines on how to
    write it, as well as <<follow-scenario>> (especially if you are writing a
    task topic).
  * If you need a *Drupal site to work with* (to try your task steps), you can
    make a temporary site at https://simplytest.me[simplytest.me]. Enter
    _drupal_ as the project, and choose the version you want to use. The site
    will stay available for 24 hours.

. *Submit your work* to the issue. See <<practicalities-submitting>> for
details.

. *Add copyright attributions information* to a comment on your issue.
See <<copyright-license>> for details.

. Make sure you get recognized for your work. See <<practicalities-recognition>>
for details.

. Update the status of your issue (in the Issue metadata section) to *_Needs
review_*, and save.

. *Subscribe to email updates for your issue*. See <<practicalities-subscribe>>
for details.

. *Check on the status* of your issue until your change is _committed_ (added to
the source file repository), and marked _Fixed_. You may be asked to make a few
changes before this happens.

. If you find that you *cannot complete this task*, see
<<practicalities-task-claim>> for instructions on how to drop a task, and
try again with a different topic.

. If you have more time, follow these steps again to write a new topic.

See also: <<management-channels>> to keep up with project announcements.


[[practicalities-editing-by-task]]
==== Quick start guide - editing tasks

During this editing phase of the project, the project managers will set up
various editing tasks for volunteers to complete. To contribute to this phase:

. *Find a task* by looking in the project_issues_link for an issue whose title
starts with "Guidelines Edit", "Copy Edit" or "Content edit", and whose
_Assigned_ field is blank. Do not choose a single-topic copy editing task for a
topic that you wrote, however, since it is never a good idea to copy edit your
own writing.

. *Claim the task* by assigning the issue to yourself. See
<<practicalities-task-claim>> for details on how to do this.

. *Complete the editing task* detailed in the issue, by editing source files on
your local computer. Make sure to *only make edits that are covered by the
guideline or task in your issue* -- other issues will cover other tasks. See:
  * <<practicalities-project>> for details on how to obtain the source files
    from the Git revision control system (this is optional if your editing
    task only affects one file, and you choose to edit using the on-line
    editor).
  * <<practicalities-editing>> for details on how to find and edit files,
    either on your local computer (if you obtained the source files from Git)
    or using the on-line editor.
  * <<formatting>> for details on how to format the text in files.

. Make a _patch file_ with your changes; however, if your task only affects a
single source file, you can skip making a patch. See <<practicalities-project>>
for patch file instructions if you need to make a patch.

. *Submit your work* to the issue. See <<practicalities-submitting>> for
details.

. *Add copyright attributions information* in a comment on your issue. See
<<copyright-license>> for details.

. Make sure you get recognized for your work. See <<practicalities-recognition>>
for details.

. Update the status of your issue (in the Issue metadata section) to *_Needs
review_*, and save.

. *Subscribe to email updates for your issue*. See <<practicalities-subscribe>>
for details.

. *Check on the status* of your issue until your change is "committed" (added to
the source file repository), and marked _Fixed_. You may be asked to make a few
changes before this happens.

. If you find that you *cannot complete this task*, see
<<practicalities-task-claim>> for instructions on how to drop a task, and
try again with a different topic.

. If you have more time, follow these steps again to complete another editing
task.

[[practicalities-translating]]
==== Quick start guide - translating tasks

Assumptions for this section:

* The project_name is currently being translated from English into your language
(that is, translation has started, and has not been completed).

* You have already contacted and joined the team that is translating the
project_name into your language. These translation teams are formed from the
software localization teams on
https://localize.drupal.org[localize.drupal.org].

Steps to translate a topic or review a translation:

. *Find a task* by looking in the project_issues_link for an open issue whose
title starts with "[LC] Translate ", where "[LC]" is the two-letter code for
your language. You can also filter the issue list by _Component_ -- there should
be a component for your language in the list. If you want to translate a topic,
look for an issue whose _Status_ field says _Active_. If you want to review a
translation, look for an issue whose _Status_ field says _Needs review_.

. *Claim the task* by assigning the issue to yourself. See
<<practicalities-task-claim>> for details on how to do this.

. *Complete the translating or reviewing task*. You will need to edit the
AsciiDoc source files on your local computer, making sure to leave the topic
structure and AsciiDoc formatting as it was in the source version. See:
  * <<practicalities-project>> for details on how to obtain the source files
    from the Git revision control system (this is optional for the initial
    translation, if you  choose to edit using the on-line editor).
  * <<practicalities-editing>> for details on how to find and edit files,
    either on your local computer (if you obtained the source files from Git)
    or using the on-line editor.
  * <<formatting>> for details on the AsciiDoc formatting that is in the source
    files.
  * <<guidelines-translating>> for general guidelines on translating.
  * Your language team's glossary, for guidelines on how to translate specific
    terms consistently in the project_name.

. Make a _patch file_ or _interdiff file_ with your changes; however, if you are
doing the initial translation, you can skip making a patch. See
<<practicalities-project>> for patch and interdiff file instructions.

. *Submit your work* to the issue. See <<practicalities-submitting>> for
details.

. Check over the *screenshot images* in your topic. They should match the
instructions and descriptions, be well cropped, and not contain any English text
(except, for instance, if the topic is about translating from English into your
language). If there are any problems, note them in a comment on your issue. If
they are fine, note that you checked them over and thought they were fine.

. *Add copyright attributions information* in a comment on your issue. See
<<copyright-license>> for details.

. Make sure you get recognized for your work. See <<practicalities-recognition>>
for details.

. Update the status of your issue (in the Issue metadata section) to *_Needs
review_*, for the initial translation. If you are reviewing a translation, you
have the choice of either:
  * Setting the status to _Needs work_, if you feel that the initial translator
    should make another attempt.
  * Setting the status to _Reviewed and tested by the community_, if you feel
    that the translation was good. Also, you can upload a new patch and an
    interdiff file, with small revisions and edits, if those are needed.

. Save the issue comment and status update.

. *Subscribe to email updates for your issue*. See <<practicalities-subscribe>>
for details.

. *Check on the status* of your issue until your change is "committed" (added to
the source file repository), and marked _Fixed_. You may be asked to make a few
changes before this happens.

. If you find that you *cannot complete this task*, see
<<practicalities-task-claim>> for instructions on how to drop a task, and
try again with a different topic.

. If you have more time, follow these steps again to complete another
translating or reviewing task.


[[practicalities-find-topic]]
==== Detailed instructions: Finding a topic to write and locating its issue

For the writing phase, we have a project_spreadsheet_link. This lists all of the
topics that need to be written, along with their status, and a link to the issue
for the writing task. You'll need to pick a topic that hasn't yet been written,
and that no one else is currently working on.

Some notes about the topic tracking spreadsheet:

image:images/spreadsheet.png["Screen shot of the tracking spreadsheet"]

* The topics are listed, one per row in the spreadsheet, within the outline of
the project_name. The left section of the sheet shows the topic names and what
they are supposed to cover.

* You'll want to find a topic that interests you, that you feel comfortable
writing, and doesn't already have a person listed as working on it. For
instance, in the screen shot above, the "Planning your Site Layout" needs
someone to write it, but "Concept: Regions in a Theme" is already being worked
on by someone else.

If after looking through the topic spreadsheet, you still need help finding a
topic to work on, see <<management>> to contact a project coordinator or find a
"sprint" work day event.


[[practicalities-task-claim]]
==== Detailed instructions: Claiming and dropping tasks

Once you have found an issue for a writing or editing task, you'll need to claim
the task by assigning the issue to yourself. Use the _Assigned_ field under
_Issue metadata_ (near the bottom of the issue page) to assign the issue to
yourself, and save the changes. Only claim a task if you think you can finish it
in about two weeks.

You may have to expand the Issue metadata section to see the fields. Here's a
screen shot; Assigned is over on the right:

image:images/issue-metadata.png["Screen shot of the issue meta-data section of
an issue"]

The project coordinators are subscribed to issues for the project, so they will
notice your change and update the tracking spreadshseet.

If you find that you cannot complete the assignment you took, or need a
different assignment, return to the issue page and do the following:

. Upload a file with whatever work you have completed, such as a
partially-written topic file, some screenshot images, or a patch file that does
some but not all of the required editing. See also
<<practicalities-submitting>>.

. Un-assign the issue (set the _Assigned_ field to _unassigned_).

. Add a comment explaining that you are not completing it.

. Submit your comment, uploads, and changes (click _Save_ at the bottom of the
issue page).

. Hopefully, find a different task to work on by following the steps above
again.


[[practicalities-editing]]
==== Detailed instructions: Viewing output and editing source files

Once you have an assigned task, your next step is to actually edit the source
file:

* For topic writing tasks, the source file name is listed in the topic
spreadsheet.

* For editing tasks, some will be related to one particular source
file (which should be noted in the issue). For others you may need to edit
several files, which you'll find by running a `grep` command at the command
line. For still others, you might be reading the project_current_output, looking
for a particular problem, and then need to edit files that exhibit that problem;
in this case, on each output page, there should be a line listing the source
file that looks like: _Source file: structure-blocks.txt_.

* For translating tasks, the source file and topic name should be noted in the
issue.

Once you figure out which source file or files you need to edit, you have two
options for editing:

* Use the online editor. This method is recommended for the initial topic
writing tasks, and some contributors prefer it for editing and translating
single topics as well. See <<practicalities-online-editor>>.

* You can download all the source files to your local computer using Git (the
revision control system the Drupal project uses), and then use any plain-text
editor to edit your file or files. This method is recommended for editing tasks,
especially if you are editing more than one file. See
<<practicalities-project>>. Instead of a plain-text editor, you can also use an
Asiidoc editor like https://github.com/asciidocfx/AsciidocFX[AsciidocFX]. Like
the online editor, an AsciiDoc editor will help you contribute without having to
immediately learn the AsciiDoc formatting language.


[[practicalities-online-editor]]
==== Detailed instructions: Using the online source editor

. Locate the current home of the project_name output: project_current_output.

. For translations, find the language you are translating into in the Languages
block, and switch to that version of the project_name. (If your language is not
shown, skip this step.)

. Find your page in the home page table of contents, or in the navigation block,
and click the link to see your page. The page output may only be a template, or
it may be a topic that was already written that you are editing.

. Scroll to the bottom, and click the _Edit AsciiDoc source file_ link.

. There is a preview button that will show you the output in a pane below as you
edit (it looks like a green check mark). Once you have opened the preview pane,
the preview should refresh each time you hit _Enter_ on your keyboard. If it
doesn't refresh automatically, click the preview button to refresh.

. For translations, there is a section on the page where you can view the text
in the source language as you translate.

. When you finish your edits, use the _Download new file_ button to download a
new version of the source file that contains your edits to your local computer.


[[practicalities-composing]]
==== Detailed instructions: Deciding what to write

If you are writing a topic (as opposed to editing an existing topic), here are
some suggestions that may help you decide what to write:

* *Start by trying to find existing documentation* for your topic that is
licensed under the same project_license license as this project. We do not want
to write completely new documentation if there is existing good documentation
that we can copy or modify. Drupal.org would be one source; you can also use
other sources, such as Wikipedia, if they are under the correct license. *If you
copy or adapt text from Drupal.org or other sources, you must attribute and list
your sources.* See <<copyright-license>> for details.

* If you are the first writer on a topic, the file should contain a template,
with instructions and notes. *Follow the instructions in the template file*,
and fill in all or most of the sections (there are instructions in the
template for what to do if you want to omit a section).

* If someone else started the writing phase and you are finishing it, the
template may not be there. There are separate templates for concept topics
(topic names start with "Concept") and task topics (topic names start with a
-ing verb); you can see find them at <<templates>>.

* *Note about screenshots*: don't worry about them being perfect - just make a
rough cut.

Before your topic is finalized for the writing phase, it will be checked for the
following:

* Does it follow the template?

* Have the comments and placeholder text been removed from the template?

* Is everything the topic was supposed to cover included, and nothing extra?

* If there are @todo notes, are they clear?

* If there are images included, do they include instructions for how to
redo them in a comment?


[[practicalities-submitting]]
==== Detailed instructions: Submitting your writing or editing

After you have selected a topic, created or assigned yourself an issue, done the
writing or editing, and possibly made some images, you will need to submit the
changes on your issue. Here are the steps:

. Log in to Drupal.org with your user name and password.

. Find your issue (try the _Your Issues_ link on your user profile page).

. Add a comment with a brief summary of what you wrote or edited. Note whether
you think it needs more work, any difficulties you encountered, any questions
you had, and any other pertinent details.

. Change the issue status to _Needs review_ (in the _Issue metadata_ section
just above the comment form).

. If you were writing a new topic, translating a topic, or if your editing task
only affected one source file, upload the text source file you edited, in the
_Files_ section of the issue (near the bottom; you may need to expand it to see
the _Upload_ button).
+
--
image:images/issue-files.png["Screen shot of the Files section of an issue"]
--

. If you made a patch or interdiff file (for editing and translating tasks),
upload that to the _Files_ section.

. If you have made screenshots or other images, also upload them to the _Files_
section.

. Make sure the attributions information for your topic is included either in
the _Issue summary_ (which you can find in the _Summary and Relationships_
section, which you may need to expand), or in a comment. See
<<copyright-license>> for instructions.
+
--
// Paste in the template from the issue create section above, put in a
// sample topic title and stuff, and take a screen shot of the Issue Summary
// section of an issue, if you need to re-create this.
image:images/issue-summary.png["Screen shot of the Issue Summary section of an issue"]
--

. Submit your comment and changes.


[[practicalities-recognition]]
==== Detailed instructions: Getting recognition for your contribution

This is a community project, and we have two ways to recognize the community
members who contribute their time to it:

. People who write, edit, or translate a topic will have their names listed (and
optionally, their organization or company names) in the attributions section at
the bottom of the topic. People who work on guide-wide tasks, such as copy
editing all topics for a specific guideline, or minor edits and proofreading,
will have their attributions information added to a guide-wide attributions
file. So, you'll need to provide this information when you work on a task (see
<<practicalities-submitting>>); when your task is complete, the project managers
will add it to the attributions section or guide-wide file, as appropriate.

. In addition, when you comment on or update any Drupal.org issue (such as those
used for tasks in this project), the Drupal.org web site will track that
contribution to the project. If you want your sponsoring organization to get
credit for your contributions, make sure to fill in the _Attribute this
contribution_ section of the issue comment form:

image:images/issue-attribution.png["Screen shot of Attribute this contribution
section of the issue comment form"]


[[practicalities-subscribe]]
==== Detailed instructions: Subscribing to email issue updates

Writing and editing tasks for this project are tracked using issues, and the
issues are the primary communication channel for tasks. So, if you are working
on a task, it is important to watch your issue for comments from the project
managers until it is finalized. You could do this by bookmarking the issue in
your browser and checking it every day or two. Alternatively, Drupal.org has a
mechanism for receiving email updates on issues:

. Log in to your Drupal.org user account, which presumably has a valid email
address in it (if not, edit your profile).

. Make sure you are _following_ your task's issue. If you updated it or added a
comment, you should be following it automatically. You can also follow any issue
by clicking the _Follow_ button on the right sidebar. (If it already says
_Following_ there, then you are already following the issue.)
+
--
image:images/issue-follow.png["Screen shot of issue follow button"]
--

. From your user profile page (click _View Profile_ in the Drupal.org
header area to get to your profile), click the _Issue notifications_ link. Make
sure the _Default notification_ says it will send email for _Issues you follow_,
and save.
--
image:images/profile-notifications.png["Screen shot of Notifications page of
user profile"]
--

[[practicalities-project]]
==== Detailed instructions: Background on Drupal.org projects, Git, and patches

The source files for both this guidelines documentation and the project_name
itself are located in a Drupal.org project: project_home_link. The source files
are managed in a Git revision control repository; the English-language files are
in subdirectory _source/en_, and other languages will eventually be in similar
subdirectories there.

This project uses Drupal.org issues to track progress on writing and editing
tasks. Every Drupal.org project has a section on the sidebar of the project page
with a count of issues and links to open issues and all issues. For this
project, here is the project_issues_link.

If you are doing an editing task that involves multiple source files, you'll
need to make a _patch file_ to submit your edits to your issue. If you're
writing a new topic, you can just submit the topic source file.

Background on Drupal.org projects and issues:

* https://www.drupal.org/node/24565[Documentation issue reports] -- The
introduction section at the top is the most relevant part; the rest is about
issues for the Drupal.org online Community Documentation, so it is not
completely relevant.

* https://www.drupal.org/node/1468332[How to find the issues for a project]

* https://www.drupal.org/node/2276011[Updating or editing an issue report]

Background on Git and patching:

* https://www.drupal.org/node/1010894[Installing Git]

* https://www.drupal.org/novice[Novice code contribution guide] - although this
is oriented towards code, the process of making a patch file for this user
guide is the same as for Drupal core and contributed modules.

* https://www.drupal.org/node/707484[Making a Drupal patch]

* https://www.drupal.org/documentation/git/interdiff[Creating an interdiff]

* All Drupal.org projects have a link on the sidebar called _Browse code
repository_, which will take you into the Git repository. From there, click
_tree_ in the top navigation to see the folders and files in the project. Here's
a link to project_cgit_link.

* All Drupal.org projects have a tab called _Version control_ that gives
specific Git instructions for that project, including instructions on how to get
a local copy of the source files and make a patch. Here's a link to
project_git_instructions_link.

Quick guide to making a patch file:

* One time: install Git. See
https://www.drupal.org/node/1010894[Installing Git].

* One time: "clone" the repository (get a local copy of the Git repository). See
project_git_instructions_link.

* Each time, before you start your task: `git pull` (update source files to
their latest versions).

* Do your editing task, using a text editor on your local computer, in the
repository directory.

* Look at the differences in the command window: `git diff`.

* When you're satisfied that they are correct, make a patch file:
  `git diff > 12345656-task-description.patch` -- in this command,
  _123456-task-description.patch_ is the name of the patch file that will be
  created. Substitute your issue number and a brief task description for the
  "123456" and "task-description" parts.

* See <<practicalities-submitting>> to submit your work to the issue.

*Attributions*

Written/edited by
https://www.drupal.org/u/jhodgdon[Jennifer Hodgdon],
https://www.drupal.org/u/eojthebrave[Joe Shindelar], and
https://www.drupal.org/u/jungle[Qiangjun Ran].
