template-osbooks-new

Template repository for creating a new osbook

Use this repository template to create an "osbooks" repository for a new book. If you instead need to create a repository for migrating an exiting book from CNX, use template-osbooks.

Overview of Steps

1. Create osbook repository - by using this template repository.
2. Customize files for new book - by editing collections/template-slug.collection.xml, META-INF/books.xml, LICENSE, and canonical.json.
3. Add user permissions* - allow people to edit the book.
4. Test your book in Gitpod - open the book inside Gitpod, try adding modules and subcollections to ensure that it works.

---

Create osbook repository

1. On GitHub, navigate to the main page of this repository (you're probably already here).

2. Above the file list, click Use this template.

3. In the Owner drop-down menu, select openstax.

4. Name the Repository:

   • osbooks-book-name, if repo contains only one collection, or
   • osbooks-book-name-bundle, if repo contains more than one collection

   Note: Repository names can be changed at a later time. Description can be left blank.

5. Set repository visibility to Private.

6. Leave Include all branches unchecked, this template repository only has one branch.

7. Click Create repository from template.

Customize files for new book

1. Once the repository is created, navigate to the COLLECTIONS folder. Edit the collection/template-slug.collection.xml

   • rename the file by replacing template-slug in the filename with the created book slug (eg. university-physics-volume-1.collection.xml).
     • if the repo is for a bundle (contain multiple books), each book will require their own collection.xml file.
   • inside the file replace:
     • the uuid with in the <md:uuid> field with one generated here (Note to CM's: make sure to add this to cnx password sheet)
     • the title in the <md:title> field
     • the slug in the <md:slug> field
     • and if necessary, the license in the <md:license> field
     • the collection number in the <md:content-id> field (Note to CM's: make sure to add this to cnx password sheet)
     • the language code in the <md:language> field. (en for english, pl for polish, or sp for spanish)
   • commit changes

2. Navigate to the META-INF folder, and edit the META-INF/books.xml

   • replace template.collection.xml in the <book href=""> field with the name of the file created in step 1
   • replace style in the <book style=""> field with the default style for the book
   • replace the book slug in the <book slug=""> field
     • if this repo is for a bundle, each book will require their own <book> field, directing too the associated collection.xml
   • commit changes

3. Navigate to the CANONICAL.JSON file and edit the canonical.json

   • add the created slug to the list.
     • if this repo is for a bundle, each book slug will need to be added to the list.
   • commit changes

4. Navigate to the LICENSE file and Copy/Paste one of the following into LICENSE file:

   • CC-BY 4.0
   • CC-BY-NC-SA 4.0
   • CC-SA 4.0
   • also update the <md:license> tag in the collection.xml to match the license, if changed from the default CC-BY license.
   • commit changes

Add user permissions

1. Change permissions with manage permissions
   1. On GitHub, navigate to the main page of this repository.
   2. On top navigation tabs, click Settings.
   3. On left navigation, click Manage access.
   4. Using the Manage Acccess panel, click the green "Invite Teams or People" to add the following teams, making sure they each have the proper role indicated below:
      • openstax/ce-all, Role: Write
      • openstax/content-managers, Role: Admin
      • openstax/ce-admins, Role: Admin
      • openstax/katalyst, Role: Read
      • {vendor account}, Role: Write (Note: find the book's vendor under column C here).
        • Wisewire: ww-openstax
        • MPS: mps-openstax
        • Six Red Marbles (SRM): srm-openstax

Final Steps

1. Open the book inside Gitpod by clicking the green gitpod button in the main book's repo. Click view using github. Try adding test modules and a test subcollection in the ToC editor to test if POET can parse the files correctly.
2. Create a card for the on Content Engineering Tech Team board
   • Issue Title: review new repository for osbook-new-book-name
   • Include link to new repository
   • Include finalization date (when repo is needed by)