Skip to content

Commit b464927

Browse files
meldrameldra
committed
Add CONTRIBUTING.md, update and expand README.md
1 parent 83ebdcf commit b464927

File tree

2 files changed

+223
-5
lines changed

2 files changed

+223
-5
lines changed

‎CONTRIBUTING.md‎

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