Warning, /epic.github.io/_collaboration/collaborative_tools.md is written in an unsupported language. File is not indexed.
0001 ---
0002 title: Collaborative Tools
0003 name: collaborative_tools
0004 layout: default
0005 ---
0006
0007 {% include layouts/title.md %}
0008
0009 #### Overview
0010
0011 * The ePIC Collaboration is currently using [Wiki](https://wiki.bnl.gov/EPIC/index.php?title=Main_Page){:target="_blank"}
0012 as its main web presence tool.
0013 Migration to this website, motivated by ease of long-term maintenance and efficient coordination of the
0014 team contributions, is work in progress. See sections below for technical information.
0015 * For meetings and agendas, there is a dedicated [ePIC Indico area](https://indico.bnl.gov/category/402/){:target="_blank"} hosted at BNL.
0016 * Ther is an extensive set of mailing lists hosted at BNL. For more information about access please contact the corresponding working group convener or a member of the leadership team.
0017
0018 ---
0019
0020 #### About this website
0021
0022 This website is work in progress. Below is the initial set of information intended to help you
0023 get started to make contributions to the content published here.
0024
0025 We leverage a very popular and efficient _static website generator_ technology:
0026 [Jekyll](https://jekyllrb.com/){:target="_blank"}.
0027 It allows the authors to use the easy-to-read [Markdown](https://www.markdownguide.org/){:target="_blank"}
0028 annotation, which is then automatically, and transparently for the user, converted into HTML. This way
0029 the cumbersome HTML editing as avoided. A simple example of the Markdown text such as used on this page
0030 may look like this:
0031
0032 ```markdown
0033 External links: [Markdown](https://www.markdownguide.org/){:target="_blank"}
0034
0035 Itemized list:
0036 * __item 1__ in bold
0037 * _item 2_ in italics
0038 ```
0039 ...which is rendered as:
0040
0041 ---
0042
0043 External links: [Markdown](https://www.markdownguide.org/){:target="_blank"}
0044
0045 Itemized list:
0046 * __item 1__ in bold
0047 * _item 2_ in italics
0048
0049 ---
0050
0051 Data content is handled in a way that effectively serves as a database,
0052 without the need to deploy an actual database server. This is achieved by storing the site data (when needed)
0053 in YAML-formatted files, which can be queried and parsed automatically.
0054 The most optimal setup for the content development is to install Jekyll on your machine using the information
0055 contained in the Jekyll link above. This requires a modicum of effort but is certainly not too difficult. It is
0056 also possible to edit the material directly on _GitHub_ (see the section below) using the state-of-the-art
0057 editor -- __VScode__. It is imperative that such direct edits, if they are necessary, are done in your own branch
0058 (as opposed to "main") so as to not accidentally damage the ePIC website by making unintended or invalid changes.
0059
0060 ##### GitHub: Managing the Content and Serving the Content
0061
0062 We use a [GitHub repository](https://github.com/eic/epic.github.io){:target="_blank"} to manage the code for this site.
0063 Basic git/GitHub literacy is very helpful for efficient participation in the development of this site's content. In terms
0064 of getting your new or updated content into the repo, the branch/pull request (PR) process is optimal.To get access to the code,
0065 create a clone of the website repository and move to the directory created:
0066
0067 ```bash
0068 git clone git@github.com:eic/epic.github.io.git
0069 cd epic.github.io
0070 ```
0071
0072 You should be able to create your own branch using the GitHub web interface, it's fairly straightforward. Then,
0073 you can use a command line like the one below, to create a working copy of the branch on your workstation or
0074 laptop:
0075
0076 ```bash
0077 git checkout my_cool_branch
0078 ```
0079
0080 After you commit the updated material to your branch and push it to GitHub, you will probably want to create
0081 a "pull request", which will prompt the administrators of this site to review your commits and merge them
0082 into main. After that the updated material will be rendered on the webpage. This is achieved by using the mechanism
0083 of ''GitHub Pages'', which is a free service provided by GitHub and which automaticall renders the site
0084 at the url: [https://eic.github.io/epic.github.io/](https://eic.github.io/epic.github.io/){:target="_blank"}
0085
0086 ##### Documents, Images, Data
0087
0088 The ePIC Collaboration is still working on its policies and technical solutions to store and manage all sorts
0089 of digital materials (e.g. PFD files, images, DOC files etc). This is work in progress. In the meantime,
0090 storage of this type of materials on this website is __strongly discouraged__ due to GitHub limitations and
0091 other factors. Links to Google Drive, Dropbox or other such cloud meadia should be used instead. Once ePIC
0092 picks the document management solution (e.g. Invenio RDM, Zenodo or something else) this will be revisited.
