Skip to content

Add more explanations about how to add information to the website #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Nov 10, 2015
Merged

Add more explanations about how to add information to the website #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1401686
update get involved page to reflect new structure and developments of…
Nov 10, 2015
65186c1
update howto to pull request workflow
Nov 10, 2015
46e0958
incorporate comments by Michel's review
Nov 10, 2015
8f594ec
incorporate second set of comments to https://github.com/HEP-SF/hep-s…
Nov 10, 2015
f2ea8ea
cleanup link anchors and upper- / lower-case mixups
Nov 10, 2015
ff5971b
add link to first mention of Liquid
Nov 10, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 32 additions & 11 deletions get_involved.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,30 +6,51 @@ layout: default

# How to get involved

Our goal is to make every effort going on as transparent and open as possible. Our official communication channel is the hep-sf-forum. Simply send a mail with ‘subscribe’ as the subject (not content) to hep-sf-forum+subscribe@googlegroups.com
Our goal is to make every effort going on as transparent and open as possible.
Our official communication channel is the hep-sf-forum. Simply send a mail with
‘subscribe’ as the subject (no content) to
hep-sf-forum+subscribe@googlegroups.com

In addition, there is a HEP S&C community mailing list for occasional HEP software and computing community mailings. Everyone involved or interested in HEP S&C is encouraged to sign up to this list. It will be used for occasional mailings of community wide interest, such as announcements of HEP S&C conferences, workshops and schools.
In addition, there is a HEP S&C community mailing list for occasional HEP
software and computing community mailings. It is not strictly related to HSF:
Everyone involved or interested in
HEP S&C is encouraged to sign up to this list. It will be used for occasional
mailings of community wide interest, such as announcements of HEP S&C
conferences, workshops and schools.

# Areas for contribution
## Areas for contribution

There are plenty of opportunities for you to contribute to the HSF, be it by participation in technical discussions, by joining one of our working groups, or by joining the HSF with your software project:
There are plenty of opportunities for you to contribute to the HSF, be it by
participation in technical discussions, by joining one of our working groups, or
by joining the HSF with your software project:

* Particpation in HSF activities and fora. See the Activities page.
* Participation in HSF events and meetings.
* Participation in HSF events and meetings.
* Taking advantage for your project from the HSF (to be created)
* Giving input to the HSF startup team
* Contributing to this website

# Meetings
## Meetings

See the Events listing on this site for information on HSF meetings, workshops, etc. Meetings use CERN indico for agenda pages. The pages are open to the world, no CERN account needed. So is Vidyo, the conference system we use. Connection info is on the indico pages. However should you need to upload material to the agenda, a CERN account is needed. CERN provides lightweight accounts to non CERN affiliated people when needed. See https://account.cern.ch/account/Externals/
See the Events listing on this site for information on HSF meetings, workshops,
etc. Meetings use CERN Indico for agenda pages. The pages are open to the world,
no CERN account needed. So is Vidyo, the conference system we use. Connection
info is on the Indico pages. However should you need to upload material to the
agenda, a CERN account is needed. CERN provides lightweight accounts to non CERN
affiliated people when needed. See https://account.cern.ch/account/Externals/

# Giving input to the HSF
## Giving input to the HSF Startup Team

In this document we provide background information, guidelines and a questionnaire for giving input to the HSF, and as background to discussions with the HSF startup team. We'd love to hear from you. If you'd like to arrange a discussion, contact any member of the startup team or email the startup team at hep-sf-startup-team@googlegroups.com.
If you are not comfortable with raising an issue in the
[forums](/forums.html] or if you are afraid that this is not the
right place for it, feel free to contact the
[HSF startup team](hep-sf-startup-team@googlegroups.com.) directly.

This page provides information on adding material to the site. It is visible to those with an editor role, which is pretty much everybody with an approved account. Information on adding content is below. To modify existing content, use the 'edit' tab you find on each content page. Questions are welcome, direct them to Torre Wenaus, wenaus@gmail.com.
## Contributing to this website

# Contributing to the HSF Knowledge Base
You are very welcome to extend this website and add information to it. You can
find instructions on how to do it [here](/howto.html).

## Contributing to the HSF Knowledge Base

The HSF provides a S&C knowledge base cataloging software in use by the community, who uses it, etc. For an introduction to the knowledge base, see the presentation on it at the SLAC workshop. The knowledge base relies on community input if it is to become comprehensive and useful. Please add, update, elaborate, correct entries for your favorite software packages, experiments, etc. All are welcome and encouraged to add and edit material.
48 changes: 28 additions & 20 deletions howto.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,23 +6,37 @@ layout: default

## About the HSF website

This site is maintained by the [HSF github repository people](https://github.com/orgs/HEP-SF/people). If you're interested to become one contact the HSF startup team or any team member. It was set up by Torre Wenaus and Benedikt Hegner.
This site is maintained by the HSF GitHub [contributors](https://github.com/orgs/HEP-SF/people). If you're interested to become one contact the HSF startup team or any team member. It was set up by Torre Wenaus and Benedikt Hegner.

## Implementation

This website is implemented using [github's Pages service](https://pages.github.com/) which makes it easy to create a website associated with a github account or project. [Pages uses Jekyll](https://help.github.com/articles/using-jekyll-with-pages/), a tool to automatically build a website from source files (which are kept in github). It supports structured sites like blogs in a simple but powerful way. We all like to work in code editors; this lets you write content in a friendly editor using the easy [markdown syntax](http://daringfireball.net/projects/markdown/syntax) (which is used by github itself).
This website is implemented using [GitHub's Pages](https://pages.github.com/) service which makes it easy to create a website associated with a GitHub account or project. Pages uses [Jekyll](https://help.github.com/articles/using-jekyll-with-pages/), a tool to automatically build a website from source files (which are kept in GitHub). It supports structured sites like blogs in a simple but powerful way.
The site content is written using the easy [Markdown syntax](http://daringfireball.net/projects/markdown/syntax) (which is used by GitHub itself).

## How to add and edit information

To create or edit files you have to use the [github repository of the HSF website](https://github.com/HEP-SF/hep-sf.github.io/), so you need to be an [HSF github repository](https://github.com/HEP-SF) user. Talk to any member of the startup team.
For adding information to this page or improving it, we follow the *[pull request](https://help.github.com/articles/using-pull-requests/)* workflow in GitHub.

If you wish (and it is recommended) you can easily set up a local instance of the newsletter site in order to preview submissions. See the [documentation on installing and running Jekyll](https://help.github.com/articles/using-jekyll-with-pages/). The website uses user pages, ie use the master branch.
Just fork our HSF [website repository](https://github.com/HEP-SF/hep-sf.github.io), edit the
files you want to edit, push them to your fork, and open a pull request.

If you only do simple operations like the ones mentioned below, the GitHub interface itself gives you all options to add and edit such files in the browser.
If you wish (and it is recommended) you can easily set up a local instance of the newsletter site in order to preview your submissions. See the [documentation](https://help.github.com/articles/using-jekyll-with-pages/)
on installing and running Jekyll.
The website uses the master branch of the hep-sf.github.io repository.

Despite this is not the recommended option, if you are not comfortable with Git
and you only want to do simple changes, the GitHub web interface allows you to
add and edit the files in your browser. In this case, you don't need to have a
local check-out of your personal fork on GitHub.

### General structure of website content files
All Markdown files of this site start with a section surrounded by `---`. This
so-called *front-matter* contains metadata about the content. Such metadata are
e.g. the author of the document or the title of the document.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd say: Despite this is not the recommended option, if you are not confortable with Git and you only want to do simple changes, the GitHub web interface allows you to add and edit the files in your browser. In this case, you don't need to have a local clone of your personal forkon GitHub.`

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd say: Despite this is not the recommended option, if you are not confortable with Git and you only want to do simple changes, the GitHub web interface allows you to add and edit the files in your browser. In this case, you don't need to have a local clone of your personal forkon GitHub.`

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

will be changed in next update.

### Adding to the newsletter

Add a new file in `workinggroups/_posts` and follow the front-matter of the
Add a new file in `newsletter/_posts` and follow the front-matter of the
other files in there. The list of news will be updated automatically.

### Adding a working group
Expand All @@ -42,23 +56,17 @@ Add a new file in `jobs/_posts` and follow the front-matter of the other files
in there. It is important to fill the field `open: true`. This field allows to
only show positions that aren't filled yet.


### Sharing and testing drafts
You can either use the github approach of forking a repository, do your changes there and make a pull request. Or if you want to store the draft into the main repository directly, you can put it into the `_drafts/` folder. Adding `--drafts` to the command line of jekyll allows you to render them locally. Once happy, `git mv` it into the `_posts/` directory and publish to the official repository.

## Technical details

### Page templates

As of writing, this website contains the following page templates:
As of writing, this website contains the following page templates for wider usage:

* default - every page inherits from this
* event
* job_summary
* job
* newsletter
* page
* plain
* event - to be used for events
* job - to be used for job postings
* newsletter - to be used for news items
* plain - to be used for standard contents

### Menu bar and automatization
The menu bar is defined in `default.html`, from which all page layouts inherit.
Expand All @@ -68,12 +76,12 @@ down menu `Working Groups`.

### Side bar and automatization
The side bar contains two dynamic blocks - *upcoming events* and *current job
openings*. Both are filled with *liquid* snippets defined in `_includes`.
openings*. Both are filled with *[Liquid](https://github.com/Shopify/liquid/wiki)* snippets defined in `_includes`.



## Useful references

- [Jekyll](http://jekyllrb.com/) to build websites from plain text
- [The liquid template engine used by Jekyll](https://github.com/Shopify/liquid/wiki)
- [markdown syntax](http://daringfireball.net/projects/markdown/syntax)
- The [Liquid](https://github.com/Shopify/liquid/wiki) template engine used by Jekyll
- [Markdown](http://daringfireball.net/projects/markdown/syntax) syntax