Make a glossary change

As explained in collaboration levels, people collaborating as editors can commit (push) changes directly to the master repository, while collaborating writers must request to have their changes merged (a pull request). Both methods are described below. But first some context for making changes that would be productive for the glossary effort at this point.

Migrating drafts from Google Drive

Anyone collaborating at the 'Writers' level and up can do this.

As explained in project phases (phase I), we're currently migrating the work originally done in Google Drive to this repository. The overall goal of phase I is to completely remove Google Drive from the workflow. This requires doing 2 things:

1. Create repository Issues for each of the existing terms in the Glossary terms register.
2. Migrate any pre-existing Google Doc drafts if they actually have any definition content. (Blank files should be deleted from Drive and Drive draft links removed from terms register.)

The terms register spreadsheet will be our means for monitoring the progress of phase I. The process for each of the above objectives are described next.

Creating term issues

We'll work in the order of Dropped/pending terms first, then Target terms.

Dropped/pending terms

We want to start with Dropped/pending terms first so the debate history is recorded/established in the right place for future discussion. This should help prevent new collaborators from proposing the same terms again unnecessarily.

The suggested workflow:

1. Go to the Glossary terms register, look in the Dropped/pending terms sheet, and check if there's a link under the Issue exists in GitHub? column.
2. If no link, create a new issue in GitHub using the title convention, term: Term name, where Term name is the actual term (e.g. term: Multichannel).
3. Make a comment in the new issue in relation to any Reasons for dropping and Counter-arguments that may exist for the term in the terms register columns. Include the names of people from who the reasons and arguments come from, if not yourself.
4. Click the "Labels" link at right of the issue comment box, and add one or more labels based on what's indicated under the Status column of the terms register:

• If status is "term dropped", add the corresponding label.
• If status is "term pending", add the corresponding label.
• If status is "needs debate", add both the "needs debate" and "term pending" labels.
• If status is blank, add both "term pending" and "needs debate" labels.

When an issue has been created for all existing terms in the Dropped/pending terms sheet of the terms register, the sheet should be deleted from the register clearly show that part is fully migrated to GitHub workflow. Any further discussions about those terms takes place using the associated issues created.

Target terms and associated draft files

After the dropped/pending terms, focus should go to the Target terms, and particularly for definition draft files that have already been started.

The suggested workflow:

1. Go to the Glossary terms register, look in the Target terms sheet, and check if there's a link under the Issue column of the Exists in GitHub repository? pair. (If yes, skip to the next step.)
2. If no issue link, look in the Google Doc status column for any entry except "Blank". (Admins will take care of "Blank" terms.)
3. For all other entries beside "Blank", create a new issue.
4. Copy the content in the old doc file, paste it into a text file,

Regarding step 2 above, repo administrators will create the necessary issues for "Blank" doc status terms, and add them in the working (https://github.com/content-strategy-forum/csf-glossary/blob/master/index.md).

Once we get that far, then collaborating writers and editors can't start working on the real meat and potatoes — the draft definitions.

Working with the repository

Before anyone with editor rights can push changes to the repository, or before writers can make a pull request, there has to be a change made to one or more repository files. Adding a new file to the repository qualifies as an uncommitted change, whether or not any edits were made to file composition. Not all changes have to be done at once. The files can be edited further anytime after the initial commit to the master repository.

With your Markdown-compatible text editor ready, try this:

1. Go to the Glossary terms register, pick a term from the list in the Target terms tab, and follow the associated draft link. (This will open the old G-doc draft file in Google Drive.)
2. Copy the content of the G-doc file, if there is anything to copy, and paste it into a new file created with the Markdown editor.
3. Save the file in .md format to your clone directory. Name it using the term the draft file is for, and use hyphens (not underscores) in place of any blank spaces (e.g., "pair-writing.md").

Jump back to your Github client. The text on the clone files context button should now read 1 Uncommitted Change. The 1 is referring to the file you just added into your cloned glossary repo. It means your clone is working correctly. You now have a change ready to commit by either push or pull request.

Switch into clone files content, if not already there, by clicking the 1 Uncommitted Change button in the toolbar. The .md file you added will appear in the file list (the only file listed) and be active by default, you'll see the contents of the file in the file display.

The display shows your file content highlighted in green only at this point, because you've added a new file, so the entire file is a "new" change. If this had been a file previously committed to the repo and you edited it afterward, unchanged regions would be in white, changed-from regions would be in red (i.e. the stuff you edited), and change-to regions would be in green (i.e. the stuff you changed the red regions to).

At this point you could add another file or more using the steps above. Each file would appear in the file list, and the context button would adjust to reflect the uncommitted file count. You could then uncheck the boxes by these files as you wish so that only checked files will be committed to the master repo.

Now we divide by access rights. Contributing writers should move to the following section for pull requests, and editors should move to the section after about push commits.

Commit (push) directly to master repository (editors)

For collaborators with rights to commit changes directory to the master repo, and have changes ready to commit, do the following:

1. Click the Sync button in the top right of the client window to sync any new master changes to your local clone. (This avoids conflicts between clone and master.)
2. Switch files view to clone context (uncommitted changes context).
3. Check the box next to the file(s) to be committed.
4. In the Summary field at bottom of the file list, add a short note (e.g. "{term} draft file added"). Skip the Description field.
5. Click the Commit and Sync master button.

It may take a moment or two, but if the commit works, the uncommitted file(s) will disappear from your files list, meaning they have successfully synced upward (committed) to the master. You just did a successful push to a repo!

Request (pull request) to have your changes merged (writers)

(steps needed)