Add CONTRIBUTING.md, update and expand README.md

CONTRIBUTING.md

@@ -0,0 +1,196 @@
+# Contributing to the CodeMeta site
+
+## Adding new Crosswalks
+
+Crosswalks are developed in
+[the main CodeMeta repository](https://github.com/codemeta/codemeta) and are
+periodically synchronised into the website.
+
+A markdown file must be created on this website before that synchronised
+Crosswalk data is displayed. Refer to existing files for examples of the
+format. The file must contain the following frontmatter fields:
+
+- `title` in the format `Crosswalk for <target>` where `<target>` is the name
+of the system the Crosswalk maps to. It can include spaces and symbols.
+- `image` in the format `/img/<filename>` where `<filename>` is the name of
+the logo filename, including extension. This file must be added to the
+`/static/img/` directory. Do *not* use the source path.
+
+The content after the frontmatter should include a short description of the
+target system. A link to the system or its metadata documentation should be
+included in this description.
+
+The following code required on the last line of the file, where
+`<source filename>` is the filename of
+[the Crosswalk source file in the main repository](https://github.com/codemeta/codemeta.github.io/tree/master/content/crosswalk),
+including spaces and symbols, but _without_ the extension:
+
+```
+{{% crosswalk name="<source filename>" %}}
+```
+
+Any other issues, requests, or contributions for the content of Crosswalks
+should go to the main repository.
+
+Please refer to the
+[instructions for contributing](https://github.com/codemeta/codemeta/?tab=contributing-ov-file)
+to that repository.
+
+## Changes for the Codemeta Generator.
+
+The CodeMeta Generator is developed in
+[its own repository](https://github.com/codemeta/codemeta-generator). GitHub
+deploys it under the same subdomain as this site.
+
+Any issues, requests, or contributions for the Generator should go there.
+
+Please refer to the
+[instructions for contributing](https://github.com/codemeta/codemeta-generator/?tab=contributing-ov-file)
+to that repository.
+
+## Pull Requests
+
+The following is the preferred process for submitting PRs regarding the
+`https://codemeta.github.io` website:
+
+Fork the `https://github.com/codemeta/codemeta.github.io` repository. This
+creates your own copy of the repository. You have full control of this copy.
+
+[![CodeMeta website forks](https://img.shields.io/github/forks/codemeta/codemeta.github.io)](https://github.com/codemeta/codemeta.github.io/fork)
+
+Clone _*your copy*_ of the repository. Where `<user>` is your github username:
+
+```
+git clone git@github.com:<user>/codemeta.github.io.git
+```
+
+There should be an issue open that discusses this change. Open a new issue if
+one does not already exist:
+
+[![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/codemeta/codemeta.github.io)](https://github.com/codemeta/codemeta.github.io/issues)
+
+(Optional) Create a new branch for your change. This keeps your `master`
+branch clear of changes, which can make it difficult to keep it in sync with
+the original repository. The following would create a branch named for issue
+#999:
+
+```
+git checkout -b "issue-999"
+```
+
+Make your changes as discussed, then run Hugo to make sure the changes are
+correct and nothing has broken.
+[Refer to the staging instructions](https://github.com/codemeta/codemeta.github.io?tab=readme-ov-file#staging-the-site)
+for how to preview your changes locally.
+
+Add and commit your changed files to your local repository copy. Include the
+issue number somewhere in a commit message, prefixed with a `#`, eg, `#999`.
+This will prompt GitHub to create a link back to the issue.
+
+Try to stick to one functional change per commit. This makes it easy to revert
+if something goes wrong.
+
+Push the commits up to GitHub:
+
+```
+git push origin issue-999
+```
+
+GitHub will prompt you to open a Pull Request. Open the Pull Request against
+the `master` branch.
+
+If the maintainers agree with your change, it will be merged. If they do not,
+it will be discussed and possibly edited in the Pull Request process.
+
+### Updating Scripts
+
+Scripts in the `/scripts/` directory of this repository process data synced
+from the main CodeMeta repository.
+
+Please check with [the main repository](https://github.com/codemeta/codemeta/)
+before updating these.
+
+### Updating Data Files
+
+Some data files in the `/data/` directory must not be manually edited in this
+repository; The `crosswalk` and `property_description` data files are
+generated during deployment and protected by `/data/.gitignore`.
+
+The files in `/data/feeds/` are checked for updates once a day. If they are
+not updating, then fixes should be applied to `.github/workflow/news.yml`.
+
+Other data files in `/data/` are discussed below.
+
+### Updating the front page features
+
+The front page layout, `landing` is divided into three sections containing
+top-level partials:
+  - `landing_left` contains the index page content,
+  - `landing_right` is narrower and contains content that is likely to change,
+  - `landing_wide` is a full-width section above the footer.
+
+A *Partial* is a fragment of the theme that can be reused. Using partials for
+complex pieces of the layout allows functionality to be moved, removed, or
+duplicated easily. A *Shortcode* is the equivalent for within `/content/`
+(instead of `/theme/`) and allow content and site functionality to be kept
+separate.
+
+Subsections that require generation from the Hugo template engine should be
+contained in partials or shortcodes. Other static theming, such as buttons,
+can be kept as inline HTML within these top-level partials.
+
+#### News Feeds
+
+The website's news feed is updated by a combination of GitHub Actions and
+Javascript. The workflow fetches the RSS feeds each day, and commits a new
+version if there are any updates. Javascript fetches any updates between
+these snapshots. This avoids an ugly jump when loading the remote feeds.
+
+To add a new feed:
+
+- Add a `curl` command to `.github/workflows/news.yml` to fetch the feed's
+URL. Use an existing command as an example.
+- Add the URL as a value to the `feeds` array under `[params]` in the site's
+`config.toml`.
+- (Optional) Add a copy of the RSS feed to `/data/feeds/`
+
+All feeds in `/data/feed/` will be merged and items are sorted by their
+`pubDate` before display.
+
+#### Supporter Acknowledgements
+
+The supporter acknowledgement cards on the landing page are built from
+`/data/supporters.json`. These cards give recognition to organisations and
+other projects that have helped to further CodeMeta's mission.
+
+To add a new supporter:
+
+- Add an object to the array in `/data/supporters.json` that contains the
+key-value pairs `name`, `logo`, and `url`.
+  - `name` should be the full name of the entity.
+  - `logo` can either be a full URL, or a path (_recommended_). As images are
+consolidated to the `/img/` directory. The path is `/img/<filename>`, where
+`<filename>` is only the filename. Do *not* use the source path.
+  - `url` should be a website, an announcement link, or funding record link.
+- If a path is provided as the value of `logo`, a file with the corresponding
+filename must be added to the `/static/img/` directory.
+
+The cards are generated sorted by name.
+
+#### RSMD Carousel
+
+If the [Research Software Metadata Guidelines](https://fair-impact.github.io/RSMD-guidelines/)
+working group releases new Aspects promoting CodeMeta, they should be added
+to carousel on the front page. The carousel is built from `/data/rsmd.json`.
+
+To add a new Aspect:
+
+- Add an object to the array in `/data/rsmd.json` that contains the key-value
+pairs `aspect`, `description`, `class`, and `link`.
+  - `aspect` is the number of the new guideline.
+  - `description` is a substring of the full guideline text.
+  - `class` is the importance classification, ie `Useful`.
+  - `link` is a direct link to the page onthe RSMD site.
+
+Keeping the JSON file ordered by the `aspect` number will make it easier to
+identify which Aspects are represented already.

README.md

@@ -1,10 +1,62 @@
 # CodeMeta Website
 
-This website is written in [Hugo](https://gohugo.io/).  Hugo is a static website engine, which is fast, popular, and easy to install and theme. See the [Hugo docs](https://gohugo.io/documentation/) for a quick orientation on how the site is organized.
+![Made with Hugo](https://img.shields.io/badge/made_with-Hugo-FF4088?logo=hugo)
+![Styled with Bootstrap](https://img.shields.io/badge/styled_with-Bootstrap-7952B3?logo=bootstrap)
 
-Before building the site, you should run the `make` command, in order to download the crosswalk locally; which is used by Hugo to generate the content of crosswalk pages.
+This is where the [`codemeta.github.io`](https://codemeta.github.io) website
+is built from, using a Static Site Generator called Hugo; a framework that
+turns Markdown into static HTML pages that can be served from anywhere. Our
+theme uses the Bootstrap framework.
 
-Then, at your option:
+We use GitHub actions to build and deploy the Hugo site to GitHub Pages. Many
+changes to the site are possible with the GitHub web interface, however for
+complex changes it will be quicker to use git directly.
 
-* To build the site to `../website`, run `hugo`. You may then open that folder in your browser, or
-* To previous the site directly without RStudio, run `hugo serve`, which will make the site available at http://localhost:1313/
+These tools have good documentation:
+
+- [Hugo documentation](https://gohugo.io/documentation/)
+- [Bootstrap documentation (currently 5.3)](https://getbootstrap.com/docs/5.3/getting-started/introduction/)
+- [GitHub Actions documentation](https://docs.github.com/en/actions)
+- [Git documentation](https://git-scm.com/docs)
+
+The website's content content often uses [JSON](https://json-schema.org/understanding-json-schema/about)
+and CodeMeta itself is based on [JSON-LD](https://json-ld.org/). Updating
+the site might involve editing such data.
+
+## Prerequisites
+
+Building the website locally may require installing a few packages. Install
+`git` and `hugo` if they are not already available.
+
+- [Git](https://gohugo.io/installation/)
+- [Hugo](https://git-scm.com/install/)
+
+_*Optional*_: If you require new Crosswalk data that is not yet synced with
+this repository, you will need `Make`.
+- deb-based: `sudo apt install build-essential`
+- rpm-based: `sudo dnf group install 'Development tools'`
+- arch-based: `sudo pacman -S base-devel`
+- Windows: through `wsl` and distro-specific package manager
+- MacOS: install `xcode` or use macports
+
+Run `make` in the `codemeta.github.io` git directory to sync the data.
+
+## Staging the site
+
+Generate the website by running `hugo` in the git directory. Hugo will output
+the files to `../website` according to configuration. If desired, set an 
+alternative path with the `--destination=<path>` option, where
+`<path>` is the desired location for the website.
+
+Hugo comes with a staging webserver. Run `hugo serve` to make hugo serve the
+website it generates. Hugo will serve the website at `http://localhost:1313`.
+Preview the site from another device by passing the options 
+`--baseURL=<host>` and `--bind=<host>`, where `<host>` is the
+desired IP or domain.
+
+A combination of the above can be used to serve the website with a standard
+web server. Use `--appendPort=false` to remove the port number from links.
+
+## Contributing to CodeMeta
+
+[Please refer to our contributing guide](https://github.com/codemeta/codemeta.github.io?tab=contributing-ov-file).