Skip to content

Latest commit

 

History

History
242 lines (174 loc) · 9.63 KB

CONTRIBUTING.md

File metadata and controls

242 lines (174 loc) · 9.63 KB
Raw

Contributing

Starting as a writer

CSC staff can join the Git organization CSCfi by sending email to [email protected]. After this you can join the CSC employees team, which gives you permissions to edit source files that build the user guide.

Making changes using pull requests

The csc-user-guide repository uses the 'master' as the default branch. You can make changes in web gui, command line or desktop application.

Master branch is protected. You cannot make changes to it directly, but you must use pull requests.

Overview

  • Create your own branch from master (or work in an already existing branch, if agreed)
  • Create / bring there the content you want to work with. Pay attention to file naming!
  • Make sure the data is 100% correct (no Taito or other old references, language is correct, commands work, style is same as in other articles)
  • When creating new article, add it also to the mkdocs.yml navigation OR in the index.md file in that folder (in case of FAQs or softwares (=apps) for example)
  • Make a pull request for your work to be added to Master
    • You can also aim it at someone specifically (recommended)
    • Assign one or more reviewers
    • Pull requests which do not meet the requirements will not be accepted. Note that you can keep committing to a pull request after it has been submitted.
    • Write meaningful pull request messages, so it is easier for reviewers to do their job.
    • Communicate! Use "WIP" (=Work In Progress) in your pull request title, if you don't wish the branch to be merged to master (i.e. you want to continue working with it).
    • Look at the test results of your PR: if they are red, check what's wrong and commit to the PR directly to fix it
  • Once PR has been accepted, remove the temporary branch

Reviewer: If you get a request to review a pull request, follow the link, edit the pages as needed (perhaps via the Web GUI), and click "comment" not "close" if you're happy with the content. Anyone can be a reviewer. Pull requests can be accepted only by a smaller group of people.

Note: If you make bigger changes to the (main) categories / menu on the left, it might effect some links used on our webpages. Please communicate these changes, for example in the RC-channel #research.csc.fi.

Previewing active branches

Preview is available for all branches: https://csc-guide-preview.rahtiapp.fi/origin/ Here you can preview your ongoing work. Note, currently absolute internal links don't work in the preview, but work on docs.csc.fi.

Making pull requests in the web GUI

In the master branch, navigate to the page you want to edit, click the pen-logo at the top right and once ready, at the bottom choose "Create new branch from this commit and start a pull request". Note, that you can give the branch a descriptive name at this point. If you wish to edit already existing branch, first change to the correct branch in the "branch" button on upper left, next to the path to the file. If you found an error in the pull request of your own branch, you can commit to it directly instead of creating another pull request (the two choices at the bottom).

Making pull requests on the command line

Overview:

  • Update local repository
  • Make a new branch from the master branch
  • Work and commit in your new branch
  • Push changes to github
  • Make a pull request to merge changes from your new branch into the develop branch
  • Ask a person to review and merge the changes

To get a copy of the repository, you need a clone it.

git clone https://github.com/CSCfi/csc-user-guide.git

All other Git commands are given inside the directory that you have cloned.

cd csc-user-guide

When you have cloned the repository, master branch is what you see. If you are unsure which branch you are in, you can run git branch. The active branch can be changed with the git checkout command.

Method:

git pull
git checkout master # switch to master branch
git checkout -b your_branch_name # create a new (temporary) branch and switch to it
# create some nice content, add files
git add example-file.md
git status # check the status
git commit -v
git push origin your_branch_name

Now you can ask a person to review and merge the changes. One can request reviewers in the Github web interface.

After the PR has been merged, the branch on github can be deleted.

Tip 1. Git uses Vim as the default editor for commit messages. It is possible to change the default editor, but below are the most important commands if you do not want to do it right now.

i    Enter insert mode
Esc  Exit insert mode
:wq  Save and exit

Tip 2. See instructions on how to write a good Git commit message.

Tip 3. If pushing fails, the most probable reason is that somebody else has made edits while you were editing. This situation is called a conflict. (To be written: How to resolve conflicts?)

Making pull requests in the desktop application

GitHub Desktop offers the third way to work with the repository.

To clone the repository, do the following:

  1. Click Current repository
  2. Click Add and select Clone repository...
  3. Find CSCfi/csc-user-guide and click Clone

Pull requests can be created as follows:

  1. Click Pull origin
  2. Click Current branch then New branch
  3. Type the name of the new branch and click Create branch
  4. Edit the files locally and commit the changes
  5. Finally click Publish branch and Create Pull Request
  6. You are directed to web gui, where you click Create pull request

Content and formatting instructions

  • Put all images in root images folder
  • Try to make standalone articles with a good name (user knows to select it from the left menu)
  • Write SLURM flags in long format (--nodes instead of -N, etc.)
  • All examples should use minimum viable reserved resources. I.e don't write examples with --t=72:00:00 / --gres=gpu:v100:4 / --cpus-per-task=40, if it not needed. Users tend to use these as default values.
  • Don't make too deep hierarchy or too many entries per subcategory (combine very small pages)
  • When in doubt, check how other pages are formatted
  • For code sections (marked with three backticks,```) Mkdocs will by default try to auto-guess the language for syntax highlighting. It's probably best to specify the language explicitly, e.g. ```bash or ```python If you don't want any syntax highlighting, just use ```text For a list of all supported languages see: http://pygments.org/docs/lexers/
  • Don't refer to the same page twice in mkdocs.yml -> sitemap breaks + weird menu action

Previewing the website using MkDocs

This user guide uses MkDocs to generate documentation pages. You can install it on your computer by following the instructions given in MkDocs documentation, or with conda by simply

conda env create -f docs/support/tutorials/conda/conda-docs-env-1.0.yaml
conda activate docs

You can start a preview web server from the command line while in the root of the project directory.

mkdocs build
mkdocs serve

This will start a web server on your computer listening on port 8000. Point your web server to localhost:8000 to get a preview of the documentation.

Bulding the website using the included Dockerfile

You can also create a Docker container to host the docs. First build an image from the included Dockerfile.

sudo docker build -t csc-user-guides .

This will build a container image called 'csc-user-guides'. Once the image is built, you can run it.

sudo docker run --rm -it -p 80:8000 --name csc-user-guides csc-user-guides

This will run a web server on your laptop in port 80. You can view the content of the user guides by pointing your browser to localhost.

Hosting the website on OpenShift

Install & authorize command line tools. For reference, see rahti documentation.

The Dockerfile is also made to be compatible with OpenShift, so it works with the source-to-image mechanism when using oc new-app. First create a new project to host the user guide.

oc new-project my-user-guide-project

Note that the name of the project must be unique within the OpenShift cluster you are running this in. Someone else may have already taken my-user-guide-project.

You can then run oc new-app to create the user guide deployment.

oc new-app https://github.com/CSCfi/csc-user-guide#feature-a --name=csc-user-guide-feature-a

In the command above, the #feature-a at the end specifies the branch to use. The option --name= is free to be chosen.

Now Rahti will build an image and a small webserver that can be exposed to internet with the oc expose command:

oc expose svc/csc-user-guide-feature-a --hostname=cug-user-guide-feature-a.rahtiapp.fi

You are free to choose any unused hostname.

Rebuilding the content is done with oc start-build command:

oc start-build csc-user-guide-feature-a

Or by setting up a webhook (see Rahti User Guide.)

If you always do your features in the branch with the same name, you only have to issue oc start-build command to have your preview of the user-guide updated.

When you are sure you don't ever need the preview website again, please either delete your project or clean it with oc delete:

oc delete all -l app=csc-user-guide-feature-a