Skip to content

Commit 3cb9de8

Browse files
moraneggmoranegg
authored
Merge pull request #90 from meldra/contrib-2025
Add CONTRIBUTING.md, update and expand README.md
2 parents 849f348 + 9fba312 commit 3cb9de8

File tree

2 files changed

+253
-5
lines changed

2 files changed

+253
-5
lines changed

‎CONTRIBUTING.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# Contributing to the CodeMeta site
2+
3+
## Adding new Crosswalks
4+
5+
Crosswalks are developed in
6+
[the main CodeMeta repository](https://github.com/codemeta/codemeta) and are
7+
periodically synchronised into the website.
8+
9+
A markdown file must be created on this website before that synchronised
10+
Crosswalk data is displayed. Refer to existing files for examples of the
11+
format. The file must contain the following frontmatter fields:
12+
13+
- `title` in the format `Crosswalk for <target>` where `<target>` is the name
14+
of the system the Crosswalk maps to. It can include spaces and symbols.
15+
- `image` in the format `/img/<filename>` where `<filename>` is the name of
16+
the logo filename, including extension. This file must be added to the
17+
`/static/img/` directory. Do *not* use the source path.
18+
19+
The content after the frontmatter should include a short description of the
20+
target system. A link to the system or its metadata documentation should be
21+
included in this description.
22+
23+
The following code required on the last line of the file, where
24+
`<source filename>` is the filename of
25+
[the Crosswalk source file in the main repository](https://github.com/codemeta/codemeta.github.io/tree/master/content/crosswalk),
26+
including spaces and symbols, but _without_ the extension:
27+
28+
```
29+
{{% crosswalk name="<source filename>" %}}
30+
```
31+
32+
Any other issues, requests, or contributions for the content of Crosswalks
33+
should go to the main repository.
34+
35+
Please refer to the
36+
[instructions for contributing](https://github.com/codemeta/codemeta/?tab=contributing-ov-file)
37+
to that repository.
38+
39+
## Changes for the Codemeta Generator.
40+
41+
The CodeMeta Generator is developed in
42+
[its own repository](https://github.com/codemeta/codemeta-generator). GitHub
43+
deploys it under the same subdomain as this site.
44+
45+
Any issues, requests, or contributions for the Generator should go there.
46+
47+
Please refer to the
48+
[instructions for contributing](https://github.com/codemeta/codemeta-generator/?tab=contributing-ov-file)
49+
to that repository.
50+
51+
## Pull Requests
52+
53+
The following is the preferred process for submitting PRs regarding the
54+
`https://codemeta.github.io` website:
55+
56+
Fork the `https://github.com/codemeta/codemeta.github.io` repository. This
57+
creates your own copy of the repository. You have full control of this copy.
58+
59+
[![CodeMeta website forks](https://img.shields.io/github/forks/codemeta/codemeta.github.io)](https://github.com/codemeta/codemeta.github.io/fork)
60+
61+
Clone _*your copy*_ of the repository. Where `<user>` is your github username:
62+
63+
```
64+
git clone [email protected]:<user>/codemeta.github.io.git
65+
```
66+
67+
There should be an issue open that discusses this change. Open a new issue if
68+
one does not already exist:
69+
70+
[![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/codemeta/codemeta.github.io)](https://github.com/codemeta/codemeta.github.io/issues)
71+
72+
(Optional) Create a new branch for your change. This keeps your `master`
73+
branch clear of changes, which can make it difficult to keep it in sync with
74+
the original repository. The following would create a branch named for issue
75+
#999:
76+
77+
```
78+
git checkout -b "issue-999"
79+
```
80+
81+
Make your changes as discussed, then run Hugo to make sure the changes are
82+
correct and nothing has broken.
83+
[Refer to the staging instructions](https://github.com/codemeta/codemeta.github.io?tab=readme-ov-file#staging-the-site)
84+
for how to preview your changes locally.
85+
86+
Add and commit your changed files to your local repository copy. Include the
87+
issue number somewhere in a commit message, prefixed with a `#`, eg, `#999`.
88+
This will prompt GitHub to create a link back to the issue.
89+
90+
Try to stick to one functional change per commit. This makes it easy to revert
91+
if something goes wrong.
92+
93+
Push the commits up to GitHub:
94+
95+
```
96+
git push origin issue-999
97+
```
98+
99+
GitHub will prompt you to open a Pull Request. Open the Pull Request against
100+
the `master` branch.
101+
102+
If the maintainers agree with your change, it will be merged. If they do not,
103+
it will be discussed and possibly edited in the Pull Request process.
104+
105+
### Updating Scripts
106+
107+
Scripts in the `/scripts/` directory of this repository process data synced
108+
from the main CodeMeta repository.
109+
110+
Please check with [the main repository](https://github.com/codemeta/codemeta/)
111+
before updating these.
112+
113+
### Updating Data Files
114+
115+
Some data files in the `/data/` directory must not be manually edited in this
116+
repository; The `crosswalk` and `property_description` data files are
117+
generated during deployment and protected by `/data/.gitignore`.
118+
119+
The files in `/data/feeds/` are checked for updates once a day. If they are
120+
not updating, then fixes should be applied to `.github/workflow/news.yml`.
121+
122+
Other data files in `/data/` are discussed below.
123+
124+
### Updating the front page features
125+
126+
The front page layout, `landing` is divided into three sections containing
127+
top-level partials:
128+
- `landing_left` contains the index page content,
129+
- `landing_right` is narrower and contains content that is likely to change,
130+
- `landing_wide` is a full-width section above the footer.
131+
132+
A *Partial* is a fragment of the theme that can be reused. Using partials for
133+
complex pieces of the layout allows functionality to be moved, removed, or
134+
duplicated easily. A *Shortcode* is the equivalent for within `/content/`
135+
(instead of `/theme/`) and allow content and site functionality to be kept
136+
separate.
137+
138+
Subsections that require generation from the Hugo template engine should be
139+
contained in partials or shortcodes. Other static theming, such as buttons,
140+
can be kept as inline HTML within these top-level partials.
141+
142+
#### News Feeds
143+
144+
The website's news feed is updated by a combination of GitHub Actions and
145+
Javascript. The workflow fetches the RSS feeds each day, and commits a new
146+
version if there are any updates. Javascript fetches any updates between
147+
these snapshots. This avoids an ugly jump when loading the remote feeds.
148+
149+
To add a new feed:
150+
151+
- Add a `curl` command to `.github/workflows/news.yml` to fetch the feed's
152+
URL. Use an existing command as an example.
153+
- Add the URL as a value to the `feeds` array under `[params]` in the site's
154+
`config.toml`.
155+
- (Optional) Add a copy of the RSS feed to `/data/feeds/`
156+
157+
All feeds in `/data/feed/` will be merged and items are sorted by their
158+
`pubDate` before display.
159+
160+
#### Supporter Acknowledgements
161+
162+
The supporter acknowledgement cards on the landing page are built from
163+
`/data/supporters.json`. These cards give recognition to organisations and
164+
other projects that have helped to further CodeMeta's mission.
165+
166+
To add a new supporter:
167+
168+
- Add an object to the array in `/data/supporters.json` that contains the
169+
key-value pairs `name`, `logo`, and `url`.
170+
- `name` should be the full name of the entity.
171+
- `logo` can either be a full URL, or a path (_recommended_). As images are
172+
consolidated to the `/img/` directory. The path is `/img/<filename>`, where
173+
`<filename>` is only the filename. Do *not* use the source path.
174+
- `url` should be a website, an announcement link, or funding record link.
175+
- If a path is provided as the value of `logo`, a file with the corresponding
176+
filename must be added to the `/static/img/` directory.
177+
178+
The cards are generated sorted by name.
179+
180+
#### RSMD Carousel
181+
182+
If the [Research Software Metadata Guidelines](https://fair-impact.github.io/RSMD-guidelines/)
183+
working group releases new Aspects promoting CodeMeta, they should be added
184+
to carousel on the front page. The carousel is built from `/data/rsmd.json`.
185+
186+
To add a new Aspect:
187+
188+
- Add an object to the array in `/data/rsmd.json` that contains the key-value
189+
pairs `aspect`, `description`, `class`, and `link`.
190+
- `aspect` is the number of the new guideline.
191+
- `description` is a substring of the full guideline text.
192+
- `class` is the importance classification, ie `Useful`.
193+
- `link` is a direct link to the page onthe RSMD site.
194+
195+
Keeping the JSON file ordered by the `aspect` number will make it easier to
196+
identify which Aspects are represented already.

‎README.md‎

Lines changed: 57 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,62 @@
11
# CodeMeta Website
22

3-
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.
3+
![Made with Hugo](https://img.shields.io/badge/made_with-Hugo-FF4088?logo=hugo)
4+
![Styled with Bootstrap](https://img.shields.io/badge/styled_with-Bootstrap-7952B3?logo=bootstrap)
45

5-
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.
6+
This is where the [`codemeta.github.io`](https://codemeta.github.io) website
7+
is built from, using a Static Site Generator called Hugo; a framework that
8+
turns Markdown into static HTML pages that can be served from anywhere. Our
9+
theme uses the Bootstrap framework.
610

7-
Then, at your option:
11+
We use GitHub actions to build and deploy the Hugo site to GitHub Pages. Many
12+
changes to the site are possible with the GitHub web interface, however for
13+
complex changes it will be quicker to use git directly.
814

9-
* To build the site to `../website`, run `hugo`. You may then open that folder in your browser, or
10-
* To previous the site directly without RStudio, run `hugo serve`, which will make the site available at http://localhost:1313/
15+
These tools have good documentation:
16+
17+
- [Hugo documentation](https://gohugo.io/documentation/)
18+
- [Bootstrap documentation (currently 5.3)](https://getbootstrap.com/docs/5.3/getting-started/introduction/)
19+
- [GitHub Actions documentation](https://docs.github.com/en/actions)
20+
- [Git documentation](https://git-scm.com/docs)
21+
22+
The website's content content often uses [JSON](https://json-schema.org/understanding-json-schema/about)
23+
and CodeMeta itself is based on [JSON-LD](https://json-ld.org/). Updating
24+
the site might involve editing such data.
25+
26+
## Prerequisites
27+
28+
Building the website locally may require installing a few packages. Install
29+
`git` and `hugo` if they are not already available.
30+
31+
- [Git](https://gohugo.io/installation/)
32+
- [Hugo](https://git-scm.com/install/)
33+
34+
_*Optional*_: If you require new Crosswalk data that is not yet synced with
35+
this repository, you will need `Make`.
36+
- deb-based: `sudo apt install build-essential`
37+
- rpm-based: `sudo dnf group install 'Development tools'`
38+
- arch-based: `sudo pacman -S base-devel`
39+
- Windows: through `wsl` and distro-specific package manager
40+
- MacOS: install `xcode` or use macports
41+
42+
Run `make` in the `codemeta.github.io` git directory to sync the data.
43+
44+
## Staging the site
45+
46+
Generate the website by running `hugo` in the git directory. Hugo will output
47+
the files to `../website` according to configuration. If desired, set an
48+
alternative path with the `--destination=<path>` option, where
49+
`<path>` is the desired location for the website.
50+
51+
Hugo comes with a staging webserver. Run `hugo serve` to make hugo serve the
52+
website it generates. Hugo will serve the website at `http://localhost:1313`.
53+
Preview the site from another device by passing the options
54+
`--baseURL=<host>` and `--bind=<host>`, where `<host>` is the
55+
desired IP or domain.
56+
57+
A combination of the above can be used to serve the website with a standard
58+
web server. Use `--appendPort=false` to remove the port number from links.
59+
60+
## Contributing to CodeMeta
61+
62+
[Please refer to our contributing guide](https://github.com/codemeta/codemeta.github.io?tab=contributing-ov-file).

0 commit comments

Comments
 (0)