Difference between revisions of "Resources/Documentation/Contribute"
m (more image formatting tweaks) |
(one more image tweak, and more content) |
||
Line 77: | Line 77: | ||
<admonition type="tip"> | <admonition type="tip"> | ||
− | [[File:git-branch.png|right| | + | [[File:git-branch.png|right|220px|frameless| An image of the GitHub branch button]] |
'''Can't find the right spot in GitHub?''' | '''Can't find the right spot in GitHub?''' | ||
Line 105: | Line 105: | ||
===Use GitHub's editor to make changes or additions=== | ===Use GitHub's editor to make changes or additions=== | ||
− | '''7.''' | + | '''7.''' When you click the "Edit" button above the text file preview, a copy of the atom-docs repository is made in your repository (associated with your GitHub account), and you'll be redirected to a web-based text editor, where you can make changes to the file via your web browser. If you are adding a new page, the text editor will be blank when it opens, and you can begin entering text. A full-screen option (called "zen mode") is included on the header bar if you need more space to work. |
+ | |||
+ | [[File:git-edit.png|center|600px|thumb|An image of the GitHub editor]] | ||
+ | |||
+ | '''8.''' Make the changes you want to the file. When you are done, scroll to the bottom of the page - next we will commit the changes. | ||
+ | |||
+ | <admonition type="important"> | ||
+ | Please review our [[Resources/Documentation/Contribution guidelines|Documentation contribution guidelines]] '''before''' submitting any changes. Thanks! | ||
+ | </admonition> | ||
===Commit the changes=== | ===Commit the changes=== | ||
+ | '''9.''' When you are finished editing and/or adding files in the text editor, scroll to the bottom of the page. You will see a box with several text fields to fill in before submitting your changes. | ||
+ | |||
+ | * '''Commit Summary''': This is a required field. [https://help.github.com GitHub Help] describes a "commit" as such: ''"Think of a commit as a snapshot of your project – code, files, everything — at a particular point in time"''. Your commit summary is a concise way to summarize the changes to the project that users will find in the commit. '''Commit summaries should be 50 characters or less''': this is more like a brief title so users can determine what has taken place at a glance. Keep it brief and to the point. Check out [http://git-scm.com/book/ch5-2.html#Commit-Guidelines these guidelines] in the Git documentation. | ||
+ | * '''Extended description''': This is an optional field, which we at Artefactual recommend using if you plan on editing our documentation. This is your chance to explain at greater length what the changes you made were, and why you felt you should make them. A concise message here will help us understand your work, and allow us to merge it into our documentation more quickly! | ||
+ | |||
+ | [[File:git-commit.png|center|600px|thumb|An image of the GitHub commit fields]] | ||
+ | |||
+ | <admonition type="tip"> | ||
+ | '''What is a commit?''' | ||
+ | |||
+ | A commit, or "revision", is an individual change to a file (or set of files). It's like when you save a file, except with Git, every time you save it creates a unique ID (a.k.a. the "SHA" or "hash") that allows you to keep record of what changes where made when and by who. Commits usually contain a commit message which is a brief description of what changes were made. (from the [https://help.github.com/articles/github-glossary/#commit GitHub Glossary]) | ||
+ | </admonition> | ||
+ | '''10.''' Once you've added a commit summary (required) and an extended description (recommended), click the "Propose File Change" button. GitHub will branch your changes, and redirect you to a page where you can compare the changes to the original, as well as submit a "pull request" to the AtoM documentation repository. | ||
+ | <admonition type="tip"> | ||
+ | '''What is a git branch?'' | ||
+ | |||
+ | If you're making an app, a website, or working on documentation collaboratively, you might have a bunch of different features, ideas, or revisions in progress at any given time - some of which are ready to go, and others which are not. By default, the main branch of a repository is usually named "master" - in the AtoM documentation repository, we name each main branch after the documentation version it represents (for example, 2.0, 2.1, 2.2, etc). By "branching" away from the main code, you create a separate instance in which you can work on your changes, and then, when they've been reviewed and tested, merge them back into the main project. This allows multiple people to collaborate at once, and a single person to work on multiple different revisions at the same time without having to finish them all on the same schedule. | ||
+ | |||
+ | With these instructions, GitHub is handling the branching automatically, so you don't have to worry! But now you know a bit more about how git (and GitHub) works. Find out more about git [http://git-scm.com/ here]. | ||
+ | </admonition> | ||
===Submit a pull request to Artefactual=== | ===Submit a pull request to Artefactual=== | ||
+ | '''11.''' Once you've finished your changes and clicked the "Propose File Change" button, GitHub will redirect you to a new page. On the bottom half of the page, you'll see a "diff" - a graphical representation of the changes you've made - the red fields with the '''-''' minus symbol in the sidebar indicate content that was changed/removed, while the green fields with the '''+''' plus symbol in the sidebar indicate the new content that was added. When you submit your changes to Artefactual, we'll be able to see this too - it offers us a quick way to understand where you've made changes, what was changed, and why. | ||
+ | [[File:git-diff.png|center|600px|thumb|An image of the GitHub diff summary]] | ||
+ | '''12.''' At the top of the page, you'll see your commit summary and description, with a reminder above it from GitHub (in blue) that the changes are still only in your repository. To submit them to Artefactual for inclusion in the AtoM documentation, click the "Send pull request" button on the right- hand side of the page. | ||
+ | [[File:git-send-pull.png|center|600px|thumb|An image of the GitHub pull request button]] | ||
+ | |||
+ | <admonition type="tip"> | ||
+ | '''What is a pull request?''' | ||
+ | |||
+ | Pull requests are proposed changes to a repository submitted by a user and accepted or rejected by a repository's collaborators (in this case, Artefactual, the maintainers of the AtoM documentation. You can see the GitHub Glossary's definition [https://help.github.com/articles/github-glossary/#pull-request here], and more information from GitHub on using pull requests [https://help.github.com/articles/using-pull-requests/ here]. | ||
+ | </admonition> | ||
+ | '''13.''' | ||
[[Category:Resources]] | [[Category:Resources]] |
Revision as of 14:16, 26 June 2015
Main Page > Resources > Resources/Documentation > Resources/Documentation/Contribute
This page describes ways in which members of the AtoM community can contribute to our public documentation - the AtoM User and Administrator's Manuals available at https://www.accesstomemory.org/docs. For more information about the documentation platform we use, and why we chose it, see: About our documentation.
Contents
Contributing documentation to the AtoM project
Want to help us improve our documentation? All AtoM documentation is publicly available under a Creative Commons Attribution-ShareAlike 4.0 Unported licence (CC BY SA). We rely on our community of users to help us keep our documentation clear, comprehensive, and easy to use - if you see something missing or broken, or have an idea about how to improve or expand upon our existing documentation, please consider getting involved. There are three main ways you can help AtoM improve its documentation:
Also, check out our Documentation contribution guidelines
Suggest minor fixes to Artefactual
See a typo or a broken link? Have a question or a minor suggestion? If you've noticed something that can be improved in our documentation, but don't have the time or resources to fix the problem yourself, we want to hear from you!
Contact us at: webmaster@accesstomemory.org
Important
AtoM documentation is freely maintained by Artefactual Systems, lead developers of the AtoM project. We do our best to ensure that our documentation is comprehensive, but as an open-source company that freely gives away software, documentation, and user support in our User Forum, please keep in mind that we have to prioritize our client assignments so that we can pay our bills and continue to provide free software and free community support. If you've submitted a suggestion for a fix to our documentation via webmaster@accesstomemory.org, thank you! If it takes us a bit of time to implement a fix, it may be because we are currently focused on a client project - we will address any reported issues as soon as we are able. As always with open-source projects, the best way to ensure a fix is implemented is to contribute the fix yourself - we encourage our community users to become active contributors to all aspects of our projects.
Contribute documentation yourself
Is there a section missing from our documentation that you'd like to see? Or a section that you'd like to improve by adding clearer instructions, more screenshots, or alternative workflows? Help us improve our documentation by submitting new or revised content yourself!
The following instructions will show you how to contribute changes to our documentation straight from our GitHub repository (here), using GitHub's user interface (GitHub Flow), which provides all the tools you need - including a text editor! If you are a more advanced user, you can do this from your own computer using a text editor and the command-line - see GitHub's incredibly useful Help documentation for guidance.
Important
Before you begin, you should:
- Create a GitHub account if you don't have one already: go to https://github.com/ and sign up - it's easy!
- Read our Documentation contribution guidelines
- Familiarize yourself with Sphinx and reStructuredText
An overview of the steps (described below):
- #Find the document you want to edit (or the place to add a new one)
- #Use GitHub's editor to make changes or additions
- #Commit the changes
- #Submit a pull request to Artefactual
- Dance! You've helped!
Find the document you want to edit
(Or the place to add a new one)
1. First, sign into your GitHub account at https://github.com (if you don't have an account yet, you'll need to create one first. You can do this on the same page.)
2. Navigate to Artefactual's AtoM Documentation repository: you can do this through the user interface by typing artefactual/atom-docs into the search bar at the top of the page:
Tip
What is a git repository?
A repository, or "repo", is simply a directory which contains your project work, as well as a few files which are used to communicate with Git. Repositories can exist either locally on your computer or as a remote copy (such as on GitHub.com). These instructions will show you how to create your own repository on GitHub.com, and then use this to submit changes to the AtoM documentation repository.
3. GitHub's user interface provides a graphical file-explorer to help you navigate through the text files in our documentation repository. The AtoM documentation repository's files are organized into folders that mimic the structure of the user manual found on the home page - for example, all files that relate to the User Manual section called "Add/Edit Content" are grouped together in a file called "add-edit-content". In GitHub, click on a folder to view its contents. Click on a .txt file to open it in-page.
Tip
Can't find the right spot in GitHub?
Don't forget to check the "Branch" drop-down - atom-docs is organized into several different branches, with the About/Contribute and FAQ docs on a different branch than the User and Admin manuals. Additionally, as we create new versions of our documentation for each major release, we will create new branches (2.0, 2.1, 2.2, etc) - so make sure you are editing or adding to the correct branch! Ideally, you will add fixes to the most recent docs, so we can carry those improvements forward.
4. If you are adding a new page, navigate into the correct folder, and click the "Add" icon next to the file path at the top of the page.
5. If you are editing an existing page, navigate to the correct reStructuredText file, so that you can see its contents previewed on GitHub's interface. Then, click the "Edit" button found above the file preview:
Tip
If you find it easier to navigate to the document you want to edit on the Access to Memory website, we've included a link directly to the related page in our GitHub repository in the right-hand navigation bar. You can find the page here on our website, and then click the "Source code" link in the sidebar - AtoM will redirect you to the relevant file in our atom-docs.git
repository.
6. GitHub will create a copy of the entire atom-docs repository in your chosen location (or in your own new repository if this is your first time using GitHub). Now you can edit to your heart's content without fear of breaking our production website or making the documents unavailable to other users. In git, this is known as "forking". At the top of the page, you'll see that now atom-docs is in your own repository (indicated by your chosen user name). You'll also see this message above the file editor, to remind you:
Use GitHub's editor to make changes or additions
7. When you click the "Edit" button above the text file preview, a copy of the atom-docs repository is made in your repository (associated with your GitHub account), and you'll be redirected to a web-based text editor, where you can make changes to the file via your web browser. If you are adding a new page, the text editor will be blank when it opens, and you can begin entering text. A full-screen option (called "zen mode") is included on the header bar if you need more space to work.
8. Make the changes you want to the file. When you are done, scroll to the bottom of the page - next we will commit the changes.
Important
Please review our Documentation contribution guidelines before submitting any changes. Thanks!
Commit the changes
9. When you are finished editing and/or adding files in the text editor, scroll to the bottom of the page. You will see a box with several text fields to fill in before submitting your changes.
- Commit Summary: This is a required field. GitHub Help describes a "commit" as such: "Think of a commit as a snapshot of your project – code, files, everything — at a particular point in time". Your commit summary is a concise way to summarize the changes to the project that users will find in the commit. Commit summaries should be 50 characters or less: this is more like a brief title so users can determine what has taken place at a glance. Keep it brief and to the point. Check out these guidelines in the Git documentation.
- Extended description: This is an optional field, which we at Artefactual recommend using if you plan on editing our documentation. This is your chance to explain at greater length what the changes you made were, and why you felt you should make them. A concise message here will help us understand your work, and allow us to merge it into our documentation more quickly!
Tip
What is a commit?
A commit, or "revision", is an individual change to a file (or set of files). It's like when you save a file, except with Git, every time you save it creates a unique ID (a.k.a. the "SHA" or "hash") that allows you to keep record of what changes where made when and by who. Commits usually contain a commit message which is a brief description of what changes were made. (from the GitHub Glossary)
10. Once you've added a commit summary (required) and an extended description (recommended), click the "Propose File Change" button. GitHub will branch your changes, and redirect you to a page where you can compare the changes to the original, as well as submit a "pull request" to the AtoM documentation repository.
Tip
'What is a git branch?
If you're making an app, a website, or working on documentation collaboratively, you might have a bunch of different features, ideas, or revisions in progress at any given time - some of which are ready to go, and others which are not. By default, the main branch of a repository is usually named "master" - in the AtoM documentation repository, we name each main branch after the documentation version it represents (for example, 2.0, 2.1, 2.2, etc). By "branching" away from the main code, you create a separate instance in which you can work on your changes, and then, when they've been reviewed and tested, merge them back into the main project. This allows multiple people to collaborate at once, and a single person to work on multiple different revisions at the same time without having to finish them all on the same schedule.
With these instructions, GitHub is handling the branching automatically, so you don't have to worry! But now you know a bit more about how git (and GitHub) works. Find out more about git here.
Submit a pull request to Artefactual
11. Once you've finished your changes and clicked the "Propose File Change" button, GitHub will redirect you to a new page. On the bottom half of the page, you'll see a "diff" - a graphical representation of the changes you've made - the red fields with the - minus symbol in the sidebar indicate content that was changed/removed, while the green fields with the + plus symbol in the sidebar indicate the new content that was added. When you submit your changes to Artefactual, we'll be able to see this too - it offers us a quick way to understand where you've made changes, what was changed, and why.
12. At the top of the page, you'll see your commit summary and description, with a reminder above it from GitHub (in blue) that the changes are still only in your repository. To submit them to Artefactual for inclusion in the AtoM documentation, click the "Send pull request" button on the right- hand side of the page.
Tip
What is a pull request?
Pull requests are proposed changes to a repository submitted by a user and accepted or rejected by a repository's collaborators (in this case, Artefactual, the maintainers of the AtoM documentation. You can see the GitHub Glossary's definition here, and more information from GitHub on using pull requests here.
13.