There’s one thing that has bugged me for a while about developing R packages. We have all these nice, modern tools we have for tracking our code, producing web sites from the roxygen documentation, an so on. Yet for every code commit I make to the master branch of a package repo, there’s often two or more additional steps I need to take to keep the package README.md and pkgdown site in sync with the code. Don’t get me wrong; it’s amazing that we have these tools available to help users get to grips with our R packages. It’s just that there’s a lot of extra things to remember to do to keep everything up to date. The development of free-to-use services such as Travis CI or Appveyor have been very useful as they can automate many of these repetitive tasks. A more recent newcomer to the field is GitHub Actions. The other day I was grappling with getting a GitHub Actions workflow to render a README.Rmd file to README.md on GitHub, so that I didn’t have to do it locally all the time. After a lot of trial and error, this is how I got it working.

The general use case I am imagining here is the package author that has a README.Rmd file that contains R code chunks, which they want to render to README.md so it will get displayed nicely on GitHub. You might want to do this to provide a simple overview of how to use some key functionality of your package or show off a plot or two that can be generated by the package. It’s pretty easy to render this locally with a Makefile or by simply invoking the correct R incantation directly in the terminal. However, wouldn’t it be great if we could automate this!

The first step in getting this working was to recognise that the R Infrastructure organisation has been working to make R-related GitHub Actions workflows available to users. This effort has been lead by Jim Hester and Jim has very helpfully provided a workflow example YAML file showing how one might go about rendering a README.Rmd file to README.md using the rmarkdown package.

1. To add image into GitHub README.md file, first upload the image into the GitHub repository. First check if there is any changes in the (remote) GitHub repository, if there is any, then pull the.
2. Do you know that many recruiters/interviewers care about candidates' Github profiles? A good Github profile can both make you more likely to pass resume sc.

A README file contains information about other files in a directory or archive of computer software. A form of documentation, it is usually a simple plain text file called Read Me, READ.ME, README.TXT, README.md (for a text file using markdown markup), README.1ST – or simply README. The file's name is generally written in uppercase letters. GitHub profile readme generator is a tool that allows you to create simple and beautiful readme that you can copy/paste and include in your profile repository as profile preview.

Also, the usethis package has made it incredibly easy to get started using GitHub Actions; usethis provides use_github_actions() to set your package up to start using GitHub Actions to check your package builds without errors. There’s also a use_github-action() function that can add workflows from the r-lib/actions repo to your package.

If you don’t have usethis installed, install it (install.packages('usethis')), then you can set your R package repo up to run R CMD check on your package on GitHub’s servers by running

in an R session in the package root folder. Running this will produce something like this

which outlines the steps usethis has taken on your behalf. The last line prints out some text that you can paste into the README.Rmd to show a status badge for the GitHub Action; in this case it will show whether or not your package passed R CMD check without error.

This also nicely illustrates how you might set things up by hand of course, especially if you don’t want to run R CMD check on each push.

GitHub Actions workflows are configurations that describe the steps in the workflow and are stored in YAML files. These files should be located in a .github/workflows folder in the package root. If all you want to do is render a README.Rmd to README.md you could just as easily create this folder yourself. I’m not sure why usethis also creates a .gitignore containing '*.html' in the .github folder, but if this is needed for what you’re doing, go ahead and create it too.

To get set-up quickly to render README.Rmd to markdown, you can now use use_github_action('render-readme.yaml'). This will copy the render-readme.yaml file from r-lib/actions/examples to .github/workflows/render-readme.yaml. Alternatively, you can touch .github/workflows/render-readme.yaml and add what you need by hand.

This is what the contents of render-readme.yaml look like, at the time of writing, if you used usethis to create it:

The first bit under on: controls when the workflow is triggered. The way the example workflow is set up means it will only be triggered if a file matching the path README.Rmd is included in the commit when pushed to the repo. It’s also worth noting that until the workflow is actually triggered, it won’t show up in the Actions tab in your repo on GitHub — this caused me no end of grief until I figured our this GitHub Actions feature. To trigger this workflow, you need to edit README.Rmd, add and commit those changes using git, and then push the changes to GitHub.

That didn’t suit my use case however; what if I change the package code in such a way that any output or plots produced by code in the README.Rmd would also change? In this case, I would have to needlessly tweak something in README.Rmd and push that change just to trigger rendering.

There’s probably a better way to do this — such as setting paths: to a wildcard that would match any.R file in the R folder so the workflow would be triggered on any change to the package code — but to just get something up and running I changed the on: part to read:

which indicates that the workflow should run for any push to the master branch of the repo.

The top-level name: element is how your workflow will be listed in the Actions tab in your repo. Set this to something short but descriptive so it is easy to filter the various outputs from workflows that are run on the GitHub Actions service.

All workflows contain one or more jobs, listed under the jobs: element. In the example YAML file, there is a single job listed as render:, which has a name, Render README.

The runs-on element indicates what system the job will be run on; here is is a Mac OS system. I’m not sure why the r-lib/actions example workflows all run on Mac OS systems? Anyway, they work, so no need to change that unless you need something specific.

The steps: section is where the stages of the job are defined.

Each of the uses: elements pulls in some pre-existing worfklow steps that you can build to upon to bootstrap the solution you need. For example, the actions/checkout@v2 workflow contains everything you need to checkout your repo and make it available to the current job. This is pretty fundamental; unless the GitHub Actions service can get at the code in your repo, it won’t be able to do anything useful whatsoever.

The next two uses: are workflows provide by r-lib/actions that set up a working R installation (r-lib/actions/setup-r@v1) and the Pandoc library used by rmarkdown (r-lib/actions/setup-pandoc@v1).

After the uses: declarations, the YAML file includes a series of steps that describe commands that are run on the service. This is where the real action takes place.

Here we see three sets of commands that will be run

1. the first installs the rmarkdown package,
2. the second runs rmarkdown::render() on README.Rmd to render it, and
3. the third commits the rendered README.md file and pushes it to your repo, or echos a comment if no changes are needed.

Notice how the run: element for the last step has a | after run:. This indicates that this particular step involves multiple lines of commands to be executed one after another.

If you’ve not come across Rscript before, it’s a way to use R like a scripting language, non-interactively. Here we’re using the -e flag to tell Rscript what R code to run, rather than passing it a .R to run.

Out of the box, these steps aren’t going to be very useful for R package maintainers if the README.Rmd uses anything other than the base R installation and recommended packages. At the very least you are going to want to also install the R package you are documenting in the README.Rmd, plus any other packages you need for the Rmd that might not be dependencies of the package in the repo.

In my case, I just needed to install the gratia package alongside rmarkdown, so I changed that run: element to be

I also decided to change the rmarkdown::render() call; by default this will generate HTML output by rendering the .Rmd first to .md and thence to .html. As we don’t need this latter step, I changed the output_format argument of render() to be 'md_document', so that element now looks like this

Doing this means I don’t also generate a README.html file (which might be why the .gitignore was created by usethis earlier?); keeping the .gitignore can’t hurt given that it only excludes any .html files from a commit, so I left it alone.

I also modified the commit step too. The default assumes you already have a README.md in the repo and that this is the only file you want to add to the commit. If you render any plots in the .Rmd, then you’ll also want to add those to the commit. So, I added an explicit git add line prior to the commit, and also simplified the latter

As you can see, I used a wildcard to catch any figures created by the render. In the README.Rmd I used a setup chunk to set the fig.pathknitr option so that any plots were generated in the man/figures folder and had the prefix README- prepended to the file name:

The man/figures folder is a useful place to store figures generated like this as they’ll be carried along with your R package and available on CRAN, where the README.md file is also displayed if present. This folder is also used if you generate and include figures in the package documentation using roxygen, for example.

I used the prefix README- so that I could limit what I was adding in the git add step of the workflow. I’m always a bit nervous when staging files for a commit and never use git commit -a for example. This way I have a reasonable means of only adding plots that were created by rendering README.Rmd.

After these changes (and a few others as I was troubleshooting some issues) my workflow to render README.Rmd files looks like this

This is a first pass at getting something working; it’s just occurred to me that the git add line probably needs to be linked with the git commit line so it only tries to commit if files were staged with git add.

It would also be good to try to cache the installed packages so the workflow doesn’t need to install everything for rmarkdown and gratia every time it is run. There’s an example of caching packages in the pkgdown action r-lib/actions/examples/pkgdown.yaml. However, I was running into issues related to the R 4.0.0 release and packages in the cache not getting refreshed even though they were out of date. So I removed that step from my pkgdown.yaml workflow, and as a result didn’t try to implement it for rendering README.Rmd files. Yet anyway…

For reference the workflow takes between two and three minutes to run on GitHub, even without package caching, which isn’t too bad, but rendering the README.Rmd locally takes only a few seconds, so there’s lots to be gained here by figuring out a reliable caching mechanism.

If you have implemented something similar for a GitHub Actions workflow, let me know in the comments below; this is all quite new to me and I’m interested in how other people might have tackled this. Now that I have this working reliably I only need to remember to git pull from GitHub more often to get the changes to README.md. The next issue I want to look at is getting the right paths: settings so the README.Rmd is rendered only when relevant files are changed in the package, not on every push to the repo.

Lastly, a big thank you to Jim Hester and everyone else who’s contributed to the R-related GitHub Actions workflows. This is an amazingly useful service for the R Community, and I for one am incredibly thankful that we have such helpful and knowledgeable people among us that are doing all this great work to make developing R packages that much easier.

Comments

Please enable JavaScript to view the comments powered by Disqus.comments powered by Disqus

Blogroll

• Down With time
• The Contemplative Mammoth
• Dynamic Ecology
• Jabberwocky Ecology
• Recology
• R Bloggers
• Andrew Barr's Ancient Eco
• Methods in Ecology & Evolution
• Musings on Quantitative Palaeoecology

Do you know that many recruiters/interviewers care about candidates’ Github profiles?

A good Github profile can both make you more likely to pass resume screening and impress the interviewer.

However only few candidates have a Github page on their resumes and most of them are not well maintained. So you definitely get better chance to stand out by keeping an up-to-date Github profile.

Format Json Github Readme

Cisco vpn no network access. In this post, I’ll tell you how to build an outstanding Github profile step by step to impress both recruiters and interviewers.

Github

GitHub is a Web-based Git repository hosting service. It offers all of the distributed revision control and source code management (SCM) functionality of Git as well as adding its own features.

Unlike Git, which is strictly a command-line tool, GitHub provides a Web-based graphical interface and desktop as well as mobile integration. It also provides access control and several collaboration features such as bug tracking, feature requests, task management, and wikis for every project.

So people can use Github to store, share and discuss both personal and corporate projects. For a well maintained profile, you can easily tell what projects the owner have worked in the past and you may even check the code.

Why is Github profile important?

For both recruiters and interviewers, it’s very important to know what each candidate has been working on in the past.

However, we all know that resume becomes less and less valuable because people tend to exaggerate their past contributions/skills and it’s extremely hard to verify. Some people may even fake their resumes.

From this perspective, Github profile is much more real.

By looking at one’s Github repositories, you can almost immediately tell if he’s an expert or beginner of a specific field.

Also number of repositories, frequency of contributions activities and maybe number of followers/followings can also reflect how passionate the owner is about programming. AFAIK, most famous programmers are quite active on Github.

As an interviewer/recruiter

When I saw someone with a very outstanding Github page, I would definitely have a great impression about him even before we met.

As a result, I was kind of convinced that he would pass the interview in my subconscious. Also I would be more likely to discuss with him about things he had worked on in the past and may write them down in the feedback.

However I could hardly get the same level of good impression by a good resume as I saw too many cases where the candidate with a perfect resume failed the simplest question.

So how to build an impressive Github profile?

Personal page on Github

It’s recommended to have your personal website and it’s totally fine if it’s just a single page.

There are many websites providing such kind of service for free like about.me, wordpress. However many people don’t know that you can also use Github to create your personal website.

The official guide from Github teaches you how to set up your site from scratch. If you know some front end development and like to build your landing page by yourself, you can definitely start working from here.

If you want to save your time from coding your personal page, you can follow these two simple guides: Making a personal site, The Absolute Noob Guide To Hosting A Personal Website Or Blog On GitHub Pages.

Here are also quite a few Github page templates.

Maintain your repositories

The rule of thumb is always keeping your Github repositories up to date.

Whenever you are working on something interesting, you can just upload it to Github. Actually you can benefit a lot from this as you can work on your projects anywhere with any computers with internet access. You can also collaborate with others.

If you don’t know what to put on your Github, here are some suggestions:

Github Readme Syntax

• Side projects. This is the number one thing I recommended. Almost all good programmers I know have a lot of side projects. They just like to code and work on things that interest them. That’s also why many companies like to ask your side projects as a way to evaluate.
• Course projects. If you are students or new grads, you must have done a lot of projects in different courses. You can choose to upload those non-trivial ones. Be careful that don’t upload code for projects that will be reused for following semesters.
• Open source projects. This is what Github is mostly famous for. There are so many open source projects on Github and most of them are maintained and contributed by passionate programmers. It’s a great chance for you to learn a lot from collaborating with them.
• Fork/Follow some projects. Sometimes you may just want to learn how it works in a project. You can fork it as your own repository and build your own version.

Also the explore section can also give you some inspiration on what’s trending on Github.

Building a good Github profile takes time as you won’t be able to come up with 10 projects in a day. Starting as early as possible is highly recommended.

Be professional

Many people use Github as a platform to collaborate with others, so it’s very important to keep everything complete and easy to understand.

If you expect to use your Github page to impress others, you’d better pay attention to this point even if you work all your projects by yourself.

1. Write clear description

Format Readme Github File

No one will read your code to understand what you are working on. Keeping your description clear and up to date makes your repositories look professional.

2. Write well formatted README

Each repository in Github can have a README file, which supports markdown format. It’s highly recommended to have README for every repository and if the project is a library, you’d better put detailed instructions in it.

3. Maybe use Issues to track bugs

It’s not necessary but you can use Github Issues to keep track of all the bugs and feature requests.

A great example is Facebook Github page. Every project is well maintained with clear description and detailed instructions.

Keep your code clean

Even if you are working by yourself, it’s still a good habit to keep your code clean.

Pay attention to your coding style, which is the most obvious way to differentiate yourself from non-professional programmers. You can follow Google style guide for Java, C++and Python, which are very popular.

Don’t leave large block of comment codes and make sure your Master branch is always workable.

Try to make your code of production quality and everything crappy should only exist on your local branches.

Avoid too many forks

It’s really annoying to look at someone’s profile with a bunch of forked repositories.

You should only fork repositories you need and nothing else. Try to clear your repositories in a regular basis. Remember that you can always re-fork back those repositories as long as they are not deleted.

Summary

Both interviewees and interviewers are complaining that 1h is too short to evaluate someone’s ability and skills, and resume is even harder to differentiate people.

Checking people’s past projects solves this problem to some extent.

As I said before, it takes time to build an impressive Github profile and the most important is to start now!

Best Github Readme

If you like this post, please share us on Facebook 🙂

Double Your Chance of Getting Hired in 45min?

Format Readme Github Online

Gainlo (gainlo.co) is a platform that allows you to have mock interview with experienced interviewers from Google, Amazon, Linkedin etc. and get real feedback to improve.

Leave your name and email to learn more about Gainlo below.

Github Profile Readme

The post is written by Gainlo - a platform that allows you to have mock interviews with employees from Google, Amazon etc.
I'd like to learn more