From b464927085649b5aa675d7550b195ead54732d9a Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Sun, 23 Nov 2025 09:54:22 -0800 Subject: [PATCH 1/3] Add CONTRIBUTING.md, update and expand README.md --- CONTRIBUTING.md | 166 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 62 ++++++++++++++++-- 2 files changed, 223 insertions(+), 5 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..82b77e3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,166 @@ +# 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. + +Any issues, requests, or contributions for Crosswalks should go there. + +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 `` is your github username: + +``` +git clone git@github.com:/codemeta.github.io.git +``` + +There should be an issue open that discusses this change. Open an 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 and commit them to your local 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. Otherwise 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/`, where +`` 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. diff --git a/README.md b/README.md index 8e40a76..8a82344 100644 --- a/README.md +++ b/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=` option, where +`` 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=` and `--bind=`, where `` 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). From 6f815a60ba484ea55512042c401e10de9f8372db Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Tue, 25 Nov 2025 13:08:08 -0800 Subject: [PATCH 2/3] Add prompt to stage site, and other minor edits --- CONTRIBUTING.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 82b77e3..c955acc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,20 +40,26 @@ Clone _*your copy*_ of the repository. Where `` is your github username: git clone git@github.com:/codemeta.github.io.git ``` -There should be an issue open that discusses this change. Open an new issue if +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: +(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 and commit them to your local copy. Include the +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. @@ -69,8 +75,8 @@ 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. Otherwise it -will be discussed and possibly edited in the Pull Request process. +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 @@ -150,8 +156,8 @@ 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`. +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: From 7736f6acf83ae69c967aa9a5f2956ccba1473d2e Mon Sep 17 00:00:00 2001 From: Melissa Draper Date: Wed, 26 Nov 2025 14:45:30 -0800 Subject: [PATCH 3/3] Update CONTRIBUTING.md with Crosswalk linking file instructions --- CONTRIBUTING.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c955acc..d890d35 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,31 @@ Crosswalks are developed in [the main CodeMeta repository](https://github.com/codemeta/codemeta) and are periodically synchronised into the website. -Any issues, requests, or contributions for Crosswalks should go there. +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 ` where `` is the name +of the system the Crosswalk maps to. It can include spaces and symbols. +- `image` in the format `/img/` where `` 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 +`` 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="" %}} +``` + +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)