Skip to content

Latest commit

 

History

History
78 lines (58 loc) · 5.51 KB

PROCESS.adoc

File metadata and controls

78 lines (58 loc) · 5.51 KB
Raw

The Open Source Way Publishing Process

The Open Source Way’s project workflow is largely dependent on the functionality of the GitHub platform. GitHub is a web-based, distributed version control tool that enables content creators to build and collaborate on text-based creations (code, prose) wherever they can connect to the internet. Before beginning work on The Open Source Way, contributors must have a GitHub account. All work done on The Open Source Way will be done within the guidebook repository of the The Open Source Way organization. This work will be under the project’s license.

The Open Source Way editorial process is divided into two distinct phases: contribution and editorial.

Contribution involves the work of creation. Contributors propose content in individual "branches," then ask project maintainers to review it and, ultimately, to merge the work into the project.

Editorial is the process of refining contributed content via numerous editorial phases. We perform this work primarily through GitHub’s issue-tracking tools, using GitHub’s web interface.

Contributing to The Open Source Way

Contributing a new chapter to The Open Source Way is relatively straightforward when you are familiar with the well-documented GitHub platform. Contributors can write materials on any system, then propose them to the project via GitHub’s web interface. Just follow these steps:

  1. Click create New File

  2. Add a file name in the name field

  3. Copy the text into the Edit new file field

  4. In the Commit new file section, add a short commit message.

  5. In the Comment field, add a short message with the number of the issue associated with the chapter (for example, "per discussion in #XX").

  6. Click the Create a new branch for this commit and start a new pull request radio button. You can use the suggested branch name.

  7. Click Propose New File. The Open a Pull Request window will open.

  8. Click the gear icon in the Reviewers pane in the right column of the page.

  9. Choose the reviewer recommended to you upon initial consultation about the chapter.

  10. Click Create pull request.

This will submit your chapter for initial review. If it meets inclusion criteria, project maintainers will merge it into the project’s main branch.

Reviewing a contribution

When receiving a request to review an initial contribution ("Draft Review" column), reviewers should use The Open Source Way editorial guidelines to approve the chapter for further editing.

When review is complete and the pull request merged, reviewers should perform one additional set of steps so subsequent editors can find the file quickly.

  1. Open the merged file in GitHub.

  2. Copy and paste the full URL for the file into the relevant issue’s comment section.

  3. On the right side of the issue, link the issue to the merged pull request.

  4. Click Comment.

Editing in The Open Source Way

When a chapter has been merged into the Main branch, it is ready to procede through the editorial process. This process will involve the following steps (or "phases"):

  1. Deverlopment edit

  2. Subject matter review

  3. Copy edit

  4. Technical edit

Each pass requires a different form of editorial and knowledge expertise, but in each pass the general editorial workflow remains the same. It looks like this:

  1. An editor will open the issue in the appropriate column on the project Editorial Board.

  2. Click the URL for the file to be edited. The file’s page will open.

  3. Click the Edit icon in the upper right section of the file’s page.

  4. Perform the appropriate editorial work on the chapter

  5. Complete at least the first field in the Commit changes field beneath the editing pane. Be sure to describe the type of editorial with you’ve performed (for example, "perform a development edit" or "formatting pass complete")

  6. Select the Create a new branch for this commit and start a pull request radio button.

    • When filling out the pull request, make sure to link the pull request back against the original issue. The issue will collect pull requests as it moves through the editorial columns.

  7. Click the Commit changes button.

  8. Another member of the Editorial team checks your change and merges the commit into the main branch.

    1. Note: They also need to reopen the issue assigned to the chapter, which is closed automatically when the pull request is merged.

An alternate process goes like this:

  1. A previous editor will link issue that is visible on the project Editorial Board to an open pulle request.

  2. An editor then uses the pull request tooling to edit and comment. FIXME: better instructions needed

  3. When the edit review is complete, the editor merges the pull request into the Main branch.

  4. The editor then needs to reopen the issue that is automatically closed when the pull request was merged.

  5. Editor can confirm that the issue moved along to the next column in the Editorial Board, if appropriate.

You can read more about pull requests in the GitHub documentation.