Editing Documentation¶
Overview¶
These documentation pages are written and maintained by volunteers from the Islandora community, and new contributions are always welcomed. The documentation that you see here is formatted in the easy-to-use Markdown markup language, which can add formatting such as links, headings, and bolded text. Then the documentation HTML site is built using mkdocs from the Markdown files hosted in the Islandora documentation GitHub repo. This documentation is rebuilt automatically upon changes being committed to GitHub, so you will see changes reflected here within a few minutes of making an edit.
The Islandora Documentation Interest Group holds regular meetings on the second Wednesday of each month between 2:00 p.m. - 3:00 p.m. EST to discuss how to improve and expand Islandora's documentation. If you are interested in becoming involved, all are welcome to join! You can view DIG meetings on the Islandora community calendar and add them to your own calendar by clicking the event and selecting "copy to my calendar". If you just want to make a contribution to the existing documentation, that process is outlined here.
Before you start¶
To edit documentation in Islandora, you must:
- have a GitHub account.
- Github accounts are free and only require a valid email address.
- have a very basic familiarity with Git terms such as fork, branch, and pull request.
- optionally, be a member of the Islandora GitHub Organization.
- To request an invite, email community@islandora.ca or ask on the Islandora Slack.
- This is only needed if you want to commit changes directly to the documentation. Non-members may still make pull requests.
- be willing to learn Markdown - a good Markdown cheat sheet can help.
- for example, you may use Markdown syntax to create links and section headings.
- follow the Islandora Documentation Style Guide.
- have either an individual Contributor License Agreement (CLA) on file with the Islandora Foundation, or work for an organization that has a corporate Contributor License Agreement on file with the Islandora Foundation.
- for information on how to fill out and submit a Contributor License Agreement (CLA) for yourself and/or your organization visit the License Agreements section of the "How to contribute" documentation page.
- by participating in the Islandora Community, you are agreeing to act according to the Islandora Code of Conduct.
How to edit documentation using a web browser¶
- Starting from the page you want to edit on a web browser, look for the pencil icon in the top righthand corner of the page and click on it.
- You will be taken to GitHub. If you are not logged in, you will be prompted to log in or register for an account. If you are logged in, you will be taken to an in-browser editor where you will view the page in Markdown.
- Make your changes directly in the browser editor, then scroll to the bottom to "commit" your changes. This is the equivalent of saving.
→ If you are not a member of the Islandora GitHub organization, GitHub will create a new fork of the documentation repository in your GitHub account. From there you can make a pull request to have your changes sent back to the main Islandora documentation repo to be reviewed and accepted.
→ If you are a member of the Islandora GitHub organization, you will be able to create a new temporary branch within the main Islandora documentation repo, and then create a pull request by selecting Create a new branch for this commit and start a pull request. Give your branch a brief name starting with your username, with no spaces, indicating what it is for. Then click Commit changes.
- You will be taken to the pull request template which will prompt you to fill out some basic information about what you have changed, and why. Replace all relevant instances of Replace this text with your own text.
- You will have the option to tag Interested Parties, or people you would like to review your work, by writing in their GitHub account name after the
@symbol. If you don't have anyone specific in mind, you may tag@Islandora/committersto alert all Islandora 8 Committers that there is a new pull request for their review.
-
When you have completed the template, submit your changes for review by clicking Create pull request.
-
Once your pull request has been made, it will go into the pull request queue and anyone tagged in the request will receive a notification. Any member of the Islandora GitHub organization can review and merge your pull request, committing your changes to the documentation, with a few exceptions:
- Your pull request should not be merged by you.
- Your pull request should not be merged by anyone who contributed to it (i.e, if some one collaborated with you on writing the changes, that person cannot merge those changes).
- Your pull request should not be merged by anyone who works at the same organization as you.
Once your changes are committed, these documentation pages will be rebuilt to reflect your changes within a few minutes.
For very minor changes
For members of the Islandora GitHub organization (i.e., those with write access to the documentation repo): If the change you made was very small, such as a formatting or spelling correction that does not change the semantics of the document, you may push your changes into the documentation immediately by selecting commit directly to the main branch and clicking Commit changes.
How to edit documentation using Git on your computer¶
Warning
These steps are for more advanced users that are familiar with using the Git source control software, which is different from just using the GitHub website with a web browser.
- For information on how to submit your Git software based changes see the Contribute code and Create a pull request sections of the "How to contribute" page of the Islandora documentation.