Documentation audit for 7.x-2.x

ruebot commented 7 years ago

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

ruebot commented 7 years ago

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.

kimpham54 commented 7 years ago

@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?

ruebot commented 7 years ago

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

ruebot commented 7 years ago

@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.

kimpham54 commented 7 years ago

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 commented 7 years ago

@ruebot

Does islandora-7x-2x-committers@googlegroups.com 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.

ruebot commented 7 years ago

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

kimpham54 commented 7 years ago

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.

ruebot commented 7 years ago

@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?

manez commented 7 years ago

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.

ruebot commented 7 years ago

@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 commented 7 years ago

@kimpham54 ping.

kimpham54 commented 7 years ago

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

kimpham54 commented 7 years ago

@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.

ruebot commented 7 years ago

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.

kimpham54 commented 7 years ago

@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 commented 7 years ago

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

ruebot commented 7 years ago

Resolved with: