From c23022a78ad95569193a17c537d9684296b60a37 Mon Sep 17 00:00:00 2001 From: Lee Hunter Date: Thu, 13 Jun 2019 11:36:56 -0400 Subject: [PATCH] add template edits to prerequisits installation add contributing add contributors remove some links that we don't use yet --- CONTRIBUTING.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 79 +++++++++++++++++++++++++++++++++------- 2 files changed, 161 insertions(+), 13 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2112d66 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,95 @@ +# How to Contribute + +There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. + +### Reporting Issues + +* Make sure you have a [GitHub account](https://github.com/signup/free) +* Submit a [Github issue](./issues) by: + * Clearly describing the issue + * Provide a descriptive summary + * Explain the expected behavior + * Explain the actual behavior + * Provide steps to reproduce the actual behavior + +### Making Changes + +* Fork the repository on GitHub +* Create a topic branch from where you want to base your work. + * This is usually the master branch. + * To quickly create a topic branch based on master; `git branch fix/master/my_contribution master` + * Then checkout the new branch with `git checkout fix/master/my_contribution`. + * Please avoid working directly on the `master` branch. + * You may find the [hub suite of commands](https://github.com/defunkt/hub) helpful +* Make commits of logical units. + * Your commit should include a high level description of your work in HISTORY.textile +* Check for unnecessary whitespace with `git diff --check` before committing. +* Make sure your commit messages are [well formed](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). +* If you created an issue, you can close it by including "Closes #issue" in your commit message. See [Github's blog post for more details](https://github.com/blog/1386-closing-issues-via-commit-messages) + +``` + Present tense short summary (50 characters or less) + + More detailed description, if necessary. It should be wrapped to 72 + characters. Try to be as descriptive as you can, even if you think that + the commit content is obvious, it may not be obvious to others. You + should add such description also if it's already present in bug tracker, + it should not be necessary to visit a webpage to check the history. + + Include Closes # when relavent. + + Description can have multiple paragraphs and you can use code examples + inside, just indent it with 4 spaces: + + class PostsController + def index + respond_with Post.limit(10) + end + end + + You can also add bullet points: + + - you can use dashes or asterisks + + - also, try to indent next line of a point for readability, if it's too + long to fit in 72 characters +``` + +* Make sure you have added the necessary tests for your changes. +* Run _all_ the tests to assure nothing else was accidentally broken. + +### Submitting Changes + +[Detailed Walkthrough of One Pull Request per Commit](http://ndlib.github.io/practices/one-commit-per-pull-request/) + +* Read the article ["Using Pull Requests"](https://help.github.com/articles/using-pull-requests) on GitHub. +* Squash the commits for your branch into one commit + * `git rebase --interactive HEAD~` ([See Github help](https://help.github.com/articles/interactive-rebase)) + * To determine the number of commits on your branch: `git log master.. --oneline | wc -l` + * Squashing your branch's changes into one commit is "good form" and helps the person merging your request to see everything that is going on. +* Make sure your branch is up to date with its parent branch (i.e. master) + * `git checkout master` + * `git pull --rebase` + * `git checkout ` + * `git rebase master` + * It is likely a good idea to run your tests again. +* Push your changes to a topic branch in your fork of the repository. +* Submit a pull request from your fork to the project. + +### Merging Changes + +* It is considered "poor from" to merge your own request. +* Please take the time to review the changes and get a sense of what is being changed. Things to consider: + * Does the commit message explain what is going on? + * Does the code changes have tests? _Not all changes need new tests, some changes are refactorings_ + * Does the commit contain more than it should? Are two separate concerns being addressed in one commit? + * Did the Travis tests complete successfully? +* If you are uncertain, bring other contributors into the conversation by creating a comment that includes their @username. +* If you like the pull request, but want others to chime in, create a +1 comment and tag a user. + +# Additional Resources + +* [General GitHub documentation](http://help.github.com/) +* [GitHub pull request documentation](http://help.github.com/send-pull-requests/) +* [Pro Git](http://git-scm.com/book) is both a free and excellent book about Git. +* [A Git Config for Contributing](http://ndlib.github.io/practices/my-typical-per-project-git-config/) diff --git a/README.md b/README.md index 7db80e4..f7057d5 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,77 @@ -# README +# COMPEL -This README would normally document whatever steps are necessary to get the -application up and running. +COMPEL is an online repository based on the Samvera/Fedora/Solr software stack intended to facilitate the preservation, discovery, and sharing of, as well as collaboration on electronic-acoustic music. -Things you may want to cover: +## Getting Started -* Ruby version +These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system. -* System dependencies +### Prerequisites -* Configuration +COMPEL is a Ruby on Rails application that relies on the Samvera Hyrax collection of gems. It also leverages the Fedora triple-store, Solr for indexing and search functionality, and FITS for file characterization. -* Database creation +* Hyrax: + - https://hyrax.samvera.org/ + - https://github.com/samvera/hyrax -* Database initialization +* Fedora: https://duraspace.org/fedora/ -* How to run the test suite +* Solr: https://lucene.apache.org/solr/ -* Services (job queues, cache servers, search engines, etc.) +* FITS: https://projects.iq.harvard.edu/fits/home -* Deployment instructions +If you would like to use VT's InstallScript tools then you will need: + +* Vagrant: https://www.vagrantup.com/ + +* Ansible: https://www.ansible.com/ + +* Virtualbox: https://www.virtualbox.org/ + +### Installing + +The easiest way to install COMPEL is to use the `InstallScripts` tool developed by University Libraries at Virginia Tech. https://github.com/VTUL/InstallScripts + +Clone the repo to your preferred location and begin by creating `ansible/site_secrets.yml` based on `ansible/example_site_secrets.yml` and editing it. + +Set the project_name to "compel" on line 7 +`project_name: 'compel'` + +Set the application environment to either development or production on line 11 +`project_app_env: 'development'` + +If running in production you must generate a secret_key_base` which can be added on line 15 +``` +# Rails "secret_key_base:" setting in config/secrets.yml. +# This MUST be set here if {{ project_app_env }} is set to "production" +# it can be generated using `openssl rand -hex 64` +project_secret_key_base: '' +``` + +Set ansible_user to "vagrant" on line 166 and uncomment the entire line. +`ansible_user: 'vagrant'` + +From the Installscripts root directory run `vagrant up` to create a new VM and provision it with the dependencies necessary to run and serve COMPEL. + + + +## Contributing + +Please read [CONTRIBUTING.md](https://github.com/VTUL/compel/blob/LIBTD-1805/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us. + +## Versioning + +We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/VTUL/compel/tags). + +## Authors + +* **Yinlin Chen @yinlinchen** +* **Lee Hunter @whunter** +* **Tingting Jiang @tingtingjh** +* **Janice Kim @shabububu** +* **Paul Mather @pmather** + +## License + +This project is licensed under the MIT License -* ...