Skip to content

How to contribute to the sciCORE Documentation

Info

Contributions are welcome! To help you getting started, we put together the tips and suggestions below.

Contributions can be made in a number of ways, a few examples are:

  1. Documentation improvements suggestions by creating a GitLab issue – please include as much detail as you can.
  2. Active participation by adding to or updating content (requires familiarity with git and Markdown)
  3. Submit feedback via issues, tickets, or email.

Creating an issue

Whether you want to submit feedback or actively contribute to the documentation page, the best way to start your contribution is to create a new issue on in the gitlab project as described below. This will help the team work on your suggested improvements in a timely and organized manner.

How to create an issue

  1. Go to git repository(after logging in with your UniBas account)
  2. Go to Issues
  3. Select New item
  4. Select the template sciCORE documentation issue template
  5. Fill in the template and include as much detail as you can

Issue naming convention

To help to categorize issues, we suggested a few conventions to name issues. When creating an issue, please follow the naming instructions below:

  1. Start the issue name with a topic
  2. Use slashes to separate parts of your issues names.
  3. Do not start your name with numbers and special characters
  4. Keep them short

Info

For example: fixing-typos or create-cheatsheet

Contributing directly (requires git and Markdown knowledge)

If you are comfortable editing Markdown, feel free to edit files either using the web interface or locally after you have cloned the repo. The main README contains the instructions to build the site locally. Please commit you changes to a branch with informative commit messages.

  1. Access the gitlab project page.
  2. Login using your university account credentials.
  3. Create an issue following the instructions above.
  4. Create a branch from the issue.
  5. Edit.
  6. Submit a merge request.

Your merge request will be reviewed by sciCORE and may be included in a future release of the documentation.

Warning

Before you start editing, please refer to the README.md file for guidelines and formatting styles used in the current documentation project.

Merge Requests From External Contributors

Warning

For merge requests from forked repositories, pipelines may start automatically but fail due to runner restrictions. Please cancel those automatically triggered pipelines.

For external contributors

  1. Fork the scicore-public-documentation project.
  2. Make your changes in your fork.
  3. Open a merge request from your fork to the upstream project.
  4. Cancel the automatically triggered merge request pipeline.
  5. Assign or notify a sciCORE project member reviewer.

Tip

If you envision contributing regularly, we can add you as a project member to avoid the need for forking and to allow pipelines to run automatically. Open an issue or send us an email to discuss this option.

For sciCORE project member reviewers

  1. Manually run the merge request pipeline from the project-member context.
  2. Confirm required jobs pass, including docs-review-build-artifact.
  3. Download the artifact from docs-review-build-artifact (the public/ folder).
  4. Review the generated website output for quality and formatting before approval.

Tip

The downloaded artifact is a static website. For smoother navigation, serve it locally instead of opening index.html directly.

  1. Extract the artifact and open the public/ folder in a terminal.
  2. Start a local web server with python3 -m http.server 8000.
  3. Open http://localhost:8000 in your browser.
  4. Stop the server with Ctrl+C when done.

Understanding lint feedback from CI

If you edit pages directly in the GitLab UI, the pipeline will still check formatting for you.

  1. Open your merge request pipeline.
  2. Open the job called docs-review-lint.
  3. Read each error in the format file:line rule message.
  4. Edit the reported line in GitLab and push/commit again.

Info

You do not need local tooling to contribute with the GitLab UI. The lint job will tell you exactly what to fix.

Common markdown fixes

  1. Headings: use a single # for page title and keep heading levels in order.
  2. Code blocks: use fenced blocks with triple backticks and a language when possible.
  3. Spacing: leave blank lines around headings, lists, and code blocks.
  4. Line breaks: avoid forced line breaks with trailing spaces; use normal paragraphs.