Documentation: Documentation audit for 7.x-2.x

Created on 14 Feb 2017 · 26Comments · Source: Islandora/documentation

We need to audit the docs directory for any mention of 7.x-2.x, and if it exists replace it with Islandora CLAW.

documentation newbie

Source

ruebot

Most helpful comment

I'd prefer to keep it generic if there's any way we can rephrase that. Just looking at how much variation has crept into something as simple as the LICENCE file on the 7.x stack, which is supposed to be identical, the fewer moving parts we maintain in these every-repo-has-one docs, the better.

manez on 28 Feb 2017

👍2

All 26 comments

Here is some help if somebody wants to tackle it:

[nruest@gorila:docs] (git)-[master]-$ grep -R "7.x-2.x" .                    
./technical-documentation/docs-build.md:This documentation is built using [mkdocs](http://www.mkdocs.org/), a static site generator that is geared towards building project documentation. The documentation is created in the [Markdown](http://en.wikipedia.org/wiki/Markdown) format, and it all resides in the [`docs`](https://github.com/Islandora-Labs/islandora/tree/7.x-2.x/docs) directory in the repository. The organization of the documenation is controlled by the [`mkdocs.yml`](https://github.com/Islandora-Labs/islandora/blob/7.x-2.x/mkdocs.yml) in the root of the repository.
./user-documentation/intro-to-claw.md:Islandora CLAW is the project name for development of Islandora to work with Fedora 4, also known as Islandora 7.x-2.x. To fully understand Islandora CLAW, it is best to start by looking at its contrasts to the previous version of Islandora, known as 7.x-1.x. 
./user-documentation/intro-to-claw.md:Islandora CLAW (or Islandora 7.x-2.x) does more than simply replace that base layer with Fedora 4. It is a total re-architecting of the interaction between the various pieces. Rather than a hamburger, Islandora CLAW is a chimera:
./contributing/templates/committerAnnounce.txt:The Islandora 7.x-2.x Project committers have asked [New Committer] to become a committer and we are pleased to announce that they have accepted.
./contributing/templates/committerInvite.txt:(on behalf of the Islandora 7.x-2.x Committers)
./contributing/CONTRIBUTING.md:That is great! In this case please send us a pull request as described in section _[Create a pull request](https://github.com/Islandora-CLAW/CLAW/blob/7.x-2.x/CONTRIBUTING.md#create-a-pull-request)_ below.
./contributing/CONTRIBUTING.md:1. [Fork](https://help.github.com/articles/fork-a-repo) the Islandora GitHub repository at [https://github.com/Islandora-CLAW/CLAW](https://github.com/Islandora-CLAW/CLAW) to your personal GitHub account. If you already have a fork of [https://github.com/Islandora/islandora](https://github.com/Islandora/islandora) Github will prevent you from creating a new fork; in such a case you can continue to use [https://github.com/Islandora/islandora](https://github.com/Islandora/islandora) to issue pull request, be cautious of which branches you work from though (you'll want to base your work off of 7.x-2.x). Also be cautious of which repository your issuing your Pull Request to (you'll want to issue your pull request to [https://github.com/Islandora-CLAW/CLAW](https://github.com/Islandora-CLAW/CLAW)). See [Fork a repo](https://help.github.com/articles/fork-a-repo) for detailed instructions.

ruebot on 16 Feb 2017

@ruebot some repositories have 8.x.-1.x, master, or both branches. In the case where there are both branches, should I mention that in contributing.md to base your work off of master or off of 8.x-1.x?

kimpham54 on 17 Feb 2017

@kimpham54 just list any repo that you have a question about, and we address them one-by-one.

ruebot on 17 Feb 2017

@kimpham54 can you gather links to all your pull requests here in a comment, and let us know when you're ready for us to review them all. You can edit the comment if need be.

ruebot on 19 Feb 2017

cleanup tasks for CONTRIBUTING.md (will continue to be updated):

remove any links that point to 7.x-2.x, make them point to master or 8.x or what the 'master' branch would be for that repository
change any mention of "Islandora and Fedora project" to Islandora CLAW project
remove mentions or links to use cases that point to islandora-deprecated/Islandora-Fedora4-Interest-Group
make sure any anchor links refer to sections in the same repository, not back to the CLAW repository
Remove suggestion to use labels. Instead suggest that they specify Use Case|Documentation|Enhancement Request in the text or title.
generic welcome message: "If you are reading this document then you are interested in contributing to the Islandora CLAW. All contributions are welcome: use-cases, documentation, code, patches, bug reports, feature requests, etc. You do not need to be a programmer to speak up!"
remove mention of PSR-2, PSR-4 compliance
issues should be opened only in the Islandora-CLAW/CLAW repository

additional notes when auditing documentation:
add a contributing.md if it doesn't exist to every repository
work on separate branch
reference the original issue in the ticket
add all links in one comment for review

kimpham54 on 21 Feb 2017

@ruebot

Does [email protected] still exist? What should the contact be here: https://github.com/Islandora-CLAW/CLAW/blob/master/docs/contributing/templates/closeCommitterVote.txt#L1
Should we have the same CONTRIBUTING.md wording in every repository with the appropriate links/reference to branches modified? I will still look at each CONTRIBUTING.md and note at any major discrepancies but will eventually replace them with the same evolving template.
Is this still true:

Fork the Islandora GitHub repository at https://github.com/Islandora-CLAW/CLAW to your personal GitHub account. If you already have a fork of https://github.com/Islandora/islandora Github will prevent you from creating a new fork; in such a case you can continue to use https://github.com/Islandora/islandora to issue pull request, be cautious of which branches you work from though (you'll want to base your work off of 7.x-2.x). Also be cautious of which repository your issuing your Pull Request to (you'll want to issue your pull request to https://github.com/Islandora-CLAW/CLAW). See Fork a repo for detailed instructions.

I'm guessing that if it is, this does not apply to every repository but only the CLAW repo?

From https://github.com/Islandora-CLAW/CLAW/blob/master/CONTRIBUTING.md#create-a-pull-request.

kimpham54 on 28 Feb 2017

Yes. That will need to be left as is.
Can you provide examples?
Only applies to the CLAW repo.

ruebot on 28 Feb 2017

Example template:
https://github.com/Islandora-CLAW/Alpaca/pull/33/files would be the template for CONTRIBUTING.md in each repository that isn't CLAW, with the only changes that need to be made for each document under Create a pull request:

Fork this repository at CHANGEME to your personal GitHub account.Be cautious of which branches you work from though (you'll want to base your work off of CHANGEME:MASTER/8.X). See Fork a repo for detailed instructions.

kimpham54 on 28 Feb 2017

@kimpham54 I'm fine with that. But, this might become a gotcha in the future when updating the document again. @manez, what do you think?

ruebot on 28 Feb 2017

manez on 28 Feb 2017

👍2

@kimpham54 we had some Islandora-CLAW GitHub org changes over the last week, so there should be less work here. How are things going on your end with this ticket?

ruebot on 9 Mar 2017

@kimpham54 ping.

ruebot on 16 Mar 2017

@ruebot sorry, just got back from vacation and didn't have my laptop. i'll be sending PRs shortly

kimpham54 on 19 Mar 2017

@ruebot @manez trying to describe forking a repository in a generic way:

Fork this repository to your personal GitHub account. Be cautious of which branches you work from though (you'll want to base your work off of the the most current stable branch - don't be afraid to ask if you're unsure which one it is). See Fork a repo for detailed instructions.

The repositories in Islandora-CLAW currently use either master or 8.x-1.x.

kimpham54 on 19 Mar 2017

Fork this repository to your personal GitHub account.

That can be a personal or institutional depending on CLAs.

You could just say something along the lines of making sure your work begins with syncing with the remote and link to this: https://help.github.com/articles/syncing-a-fork/

The repositories in Islandora-CLAW currently use either master or 8.x-1.x.

All Drupal modules use the Drupal version branch convention. Everything else is master.

ruebot on 20 Mar 2017

@ruebot @manez https://github.com/Islandora-CLAW/Alpaca/pull/37 is ready for review. I've closed all other PRs for now. If the CONTRIBUTING.md looks good, I will start creating pull requests for the other repositories with the same CONTRIBUTING.md

kimpham54 on 20 Mar 2017

@ruebot @manez Updated Islandora-CLAW/Alpaca#37 - please review

kimpham54 on 20 Mar 2017

Resolved with: