Merge pull request #19 from web-illinois/update-readme

Update readme

.github/workflows/deploy_main.yml

@@ -13,7 +13,19 @@ jobs:
 
     - run: npm install
     - run: npm rebuild
-    - run: npm run-script gulp
+    - name: Run Gulp for ils-contentslider
+      run: npm run-script gulp ils-contentslider 
+    - name: Run Gulp for ils-twitter
+      run: npm run-script gulp ils-twitter 
+    - name: Run Gulp for ils-google-analytics
+      run: npm run-script gulp ils-google-analytics 
+    - name: Run Gulp for ils-input
+      run: npm run-script gulp ils-input 
+    - name: Run Gulp for ils-status
+      run: npm run-script gulp ils-status 
+    - name: Run Gulp for ils-xtwitter
+      run: npm run-script gulp ils-xtwitter 
+
     - name: Configure AWS Credentials
       uses: aws-actions/configure-aws-credentials@v1
       with:

.github/workflows/restrict_main_pr.yml

@@ -8,6 +8,3 @@ jobs:
     steps:
     - name: Echo branches
       run: echo "PR request from ${{ github.base_ref }} to ${{ github.head_ref }}"
-    - name: Confirm develop is the source branch
-      if: ${{ github.head_ref != 'develop' }}
-      run: exit 1

gulpfile.js

@@ -1,4 +1,3 @@
-// each file in GulpTasks should contain a serial task that runs all tasks inside it
 require('./ils-contentslider/gulpfile.js');
 require('./ils-twitter/gulpfile.js');
 require('./ils-google-analytics/gulpfile.js');
@@ -7,5 +6,3 @@ require('./ils-status/gulpfile.js');
 require('./ils-xtwitter/gulpfile.js');
 
 const gulp = require('gulp');
-
-gulp.task('default', gulp.parallel('ils-contentslider', 'ils-twitter', 'ils-google-analytics', 'ils-input', 'ils-status', 'ils-xtwitter' ));

readme.md

@@ -1,26 +1,68 @@
-# WIGG Shared Components
+# Shared Components
 
 ## What is this? 
 
-This contains code that small groups have built to make their life easier in coordination with the [Illinois Toolkit](https://go.illinois.edu/webtoolkit). Unlike [the formal WIGG groups](https://webtheme.illinois.edu/about/), this is distributed and "bottom-up" -- a way to crowdsource and share solutions without having to merge these changes to a common codebase.
+The [web-illinois Github organization](https://github.com/web-illinois) is meant for developers to share code. The traditional way to share client-side (JS and CSS) code is to [create and publish an NPM package](https://www.freecodecamp.org/news/how-to-create-and-publish-your-first-npm-package/). However, creating a package requires some skill on both the developer (to create the package) and the end user (to consume the package). You can also take your code on Github and [host your code on a cPanel instance](https://web.illinois.edu/). However, this requires some additional work to create the cPanel instance and copy the code from Github to cPanel, and there's no guarantee that the code on Github is the same as on the cPanel instance. 
 
-Shared components may be formal web components, javascript that checks for "data-" tags, or CSS classes that help with formatting (or all three). Shared components should be usable across multiple platforms. We recommend keeping the dependencies needed to use a shared component to a minimum. 
+This shared components repository is a low-effort way to put files in Github, and these files will be pushed to a Tech Services AWS S3 bucket. Unlike [Illinois Toolkit](https://go.illinois.edu/webtoolkit) and [the formal WIGG groups](https://webtheme.illinois.edu/about/), this is distributed and "bottom-up" -- a way to crowdsource and share solutions without having to combine the code into a single monolithic javascript and CSS file. 
 
-Because this is distributed, WIGG doesn't have any code review process in terms of accessibility, security, cross-platform use, or usability. 
+An end user can then consume your code by adding HTML tags like the following (using *ils-input* as an example):
+
+    <script src="//contrib.webtheme.illinois.edu/ils-input/input.min.js"></script>
+    <link rel="stylesheet" href="//contrib.webtheme.illinois.edu/ils-input/input.min.css" media="all">
+
+**Each folder in this repository is independent of each other.** This may mean that using multiple components is "chatty" and requires multiple calls to the contrib.webtheme.illinois.edu URL, but that is the trade-off of using this method. 
+
+Despite this being called "shared components", this isn't limited to web components. Contents may include (but are not limited to)
+* Formal web components
+* Vanilla JavaScript files
+* jQuery files
+* CSS files
+* Images and other resources
+* JSON data files
+
+## Use and Expectations
+
+1. **Everything is *use as is*.** There are no code review process in terms of accessibility, security, cross-platform use, or usability. 
+2. Authors are responsible for their own components inside this github repository.
+3. If an author is going to pull or drastically change a component, they need to contact everyone listed on the component's README.md file.
+4. Users are responsible for keeping current the list of components they are using (via the components' README.md files) 
 
 ## How to get started
 
-If you need a component, first check to see if someone else wants it! Go to the ["Need Component" issue section](https://github.com/web-illinois/shared-components/labels/need%20component) and the ["Have Component" issue section](https://github.com/web-illinois/shared-components/labels/have%20component) and scan if something there meets your needs. If nothing there works, then post an issue and give it the "Need Component" label. 
+### If you need something 
+
+First check to see if someone else wants or has it! Go to the ["Need Component" issue section](https://github.com/web-illinois/shared-components/labels/need%20component) and the ["Have Component" issue section](https://github.com/web-illinois/shared-components/labels/have%20component) and scan if something there meets your needs. If nothing there works, then post an issue and give it the "Need Component" label. 
+
+### If you want to contribute a new item
+
+Again, first check to see if someone else wants it or if someone else built it already. Go to the ["Need Component" issue section](https://github.com/web-illinois/shared-components/labels/need%20component) and scan if something there meets your needs. If no one needs it, [create an issue](https://github.com/web-illinois/shared-components/issues) and give it the "Have Component" label. 
+
+### If you wish to use an existing component "as is"
+
+You can either access the files directly on `https://contrib.webtheme.illinois.edu`, or copy the files and host them on your website. Contact the owner first so they can add you to the README.md of the component, or add your area to the component README.md file. 
 
-If you want to contribute a component, again, first check to see if someone else wants it or if someone else built it already. Go to the ["Need Component" issue section](https://github.com/web-illinois/shared-components/labels/need%20component) and scan if something there meets your needs. If no one needs it, [create an issue](https://github.com/web-illinois/shared-components/issues) and give it the "Have Component" label. 
+### If you wish to change an existing component 
 
-If you wish to use an existing component, you can either access the files directly on `https://contrib.webtheme.illinois.edu`, or copy the files and host them on your website. Because this is tied to the Illinois Toolkit, you should have this installed on your website. 
+For example, the component does 95% of what you want it to do, or there's a bug that prevents you from using it. Contact the owner before making any changes. 
+
+## Map of the shared components
+
+### Packages
+
+The shared-components uses NPM and [`package.json`](https://github.com/web-illinois/shared-components/blob/main/package.json) to manage the build process. You are not required to any existing packages. If you need to add additional packages, feel free. Ensure that any packages that are added don't interfere with other components, and try to use existing packages when possible. 
+
+### Continuous Integration 
+
+Any changes to the main branch gets pushed to the `https://contrib.webtheme.illinois.edu` site. Please make sure you create a branch, then merge to main. Do not make changes directly to the main branch. 
+
+If you need the continuous integration to build your code, modify the `package.json` to add a script and [`deploy_main.yml`](https://github.com/web-illinois/shared-components/blob/main/.github/workflows/deploy_main.yml) to include your npm script in the build process. 
 
 ## Rules (or "How to Get Along")
 
-It's tempting, but do not post something just because it is cool. This is for collaboration, so make sure that another college or department needs the component you are committing. If you aren't sure, post an issue with the ["Have Component" label](https://github.com/web-illinois/shared-components/labels/have%20component) and see if someone else requests it. 
+It's tempting, but do not contribute something just because it is cool. This is for collaboration, so make sure that another college or department needs the component you are committing. If you aren't sure, post an issue with the ["Have Component" label](https://github.com/web-illinois/shared-components/labels/have%20component) and see if someone else requests it. 
 
-Shared components should have a namespace of "ils-{xxxxxxxx}" for their web component, data tags, or CSS classes. All components, data tags, and CSS classes should use this namespace.
+I recommend that shared components have a namespace of "ils-{xxxxxxxx}" for their web component, data tags, or CSS classes. All components, data tags, and CSS classes should use this namespace.
 
 ### Good examples of namespace use:
 
@@ -34,8 +76,6 @@ Shared components should have a namespace of "ils-{xxxxxxxx}" for their web comp
     <div class="ils-twitter"><div class="block-flex"><div class="item">...</div></div></div>
     <div class="ils-contactinfo" data-name="EducationHR">...</div>
 
-Shared components should be self-contained in a single folder -- you shouldn't have one shared component dependent on another shared component. The folder name should be the namespace of the shared component.
-
 Shared components should have a README.md file at their root directory. 
 
 ### README.md file contents
@@ -49,13 +89,7 @@ Shared components should have a README.md file at their root directory.
     * Abandoned on xx/yy/zzzz: This never met production status and should not be used. 
 * Any dependencies this component needs (a specific version of the Illinois Toolkit, bootstrap, jQuery, etc.).  
 * Examples or information on how to use this. Include code snippets of what files need to be included.
-* A userlist of other developers that use this.
-
-## Continuous Integration and Gulp
-
-Any changes to the main branch gets pushed to the `https://contrib.webtheme.illinois.edu` site. Please make sure you create a branch with your Net ID, merge to develop, then merge to main. Do not make changes directly to the main branch or develop branch. 
-
-This project has a gulp project. As more projects get built, you can use this to run gulp tasks. Do not add tasks directly to the gulp file -- include the gulp file in the main gulp file, then trigger it in the main gulp file. 
+* A userlist of other areas on campus that use this.
 
 ## Run into problems?