"Fossies" - the Fresh Open Source Software Archive

Member "brlcad-7.32.4/doc/GITHUB" (29 Jul 2021, 4841 Bytes) of package /linux/misc/brlcad-7.32.4.tar.bz2:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 BRL-CAD has migrated from the Sourceforge hosting solution
    2 (https://sf.net/projects/brlcad) to Github (https://github.com/BRL-CAD/brlcad).
    3 As with other large projects that have undertaken large scale hosting and VCS
    4 migration(1) the BRL-CAD project is adjusting to working in the new
    5 environment.  The following notes are intended to capture practical tips and
    6 information related to working with BRL-CAD on the Github platform.
    7 
    8 --------------------------------------------------------------------------------
    9 For those wishing to direct Github emails to different addresses on a
   10 per-project basis, the following information may be useful:
   11 
   12 https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#customizing-email-routes-per-organization
   13 
   14 --------------------------------------------------------------------------------
   15 Using Github Actions to iteratively debug problems.
   16 
   17 Github's runners (build platforms for it's Actions CI system) offer a way to
   18 test platforms we don't otherwise have access to.  Sometimes, if we need to
   19 iteratively test inputs being supplied to tools on those platforms to diagnose
   20 a problem, the full configure/build/test cycle can be a very slow way to
   21 proceed.
   22 
   23 A way forward in this case is to create a temporary local repository with a
   24 checking of the binary version of BRL-CAD used for the specific platform in
   25 question, along with test inputs and an action defined to run the specific test
   26 in question. (REMEMBER - github repos are public, so only define and use inputs
   27 suitable for public consumption!)
   28 
   29 For the below example, we created a repository with the Windows binary install
   30 and a README file explaining what the test is doing:
   31 
   32 -rw-rw-r--   1 user user    72 Sep 23 17:52 README
   33 drwxrwxr-x   3 user user 12288 Sep 24 07:41 bin
   34 drwxrwxr-x   4 user user  4096 Sep 23 17:49 libexec
   35 drwxrwxr-x  13 user user  4096 Sep 23 17:50 lib
   36 drwxrwxr-x   5 user user  4096 Sep 23 17:49 include
   37 drwxrwxr-x  16 user user  4096 Sep 23 17:50 share
   38 drwxrwxr-x   8 user user  4096 Sep 24 07:42 .git
   39 drwxrwxr-x   3 user user  4096 Sep 23 17:53 .github
   40 
   41 Then, in the .github/workflows directory we create a .yml file to trigger the
   42 test whenever we push a change.  For this example we were wanting to test the
   43 benchmark script, so we create a .github/workflows/benchmark.yml file with the
   44 following contents:
   45 
   46 name: benchhmark
   47 on: [push]
   48 jobs:
   49   bench:
   50     runs-on: windows-latest
   51     steps:
   52       - uses: actions/checkout@v2
   53       # https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#adding-a-system-path
   54       - run: echo '::add-path::{C:\Program Files\Git\bin}'
   55       - run: sh.exe ./bin/benchmark run
   56 
   57 This allowed developers to iteratively adjust the bin/benchmark shell script
   58 and test the results in the compilation Windows environment, *without* having
   59 to perform the full compilation cycle on Windows each time.  Once a working
   60 benchmark script was identified it was added back to the primary repository and
   61 the test repo deleted.
   62 
   63 --------------------------------------------------------------------------------
   64 Debugging flags can be added to the actions environment for a given repo:
   65 
   66 https://github.community/t/ci-access-to-shell-session/17250
   67 
   68 (Note:  the "Secrets" label is misleading in this particular case - that is
   69 the mechanism by which the values are introduced into the runner environment,
   70 but there are no actual secrets contained in the values of the debugging
   71 variables.)
   72 
   73 --------------------------------------------------------------------------------
   74 Git provides a stats page, but that page reports only commits to the "main"
   75 branch.  To prepare a more comprehensive stats page, one alternative that has
   76 been tested is:
   77 
   78 https://github.com/tomgi/git_stats
   79 
   80 After installing, statistics pages can be generated by running:
   81 the following in a clone of the repository.
   82 
   83 user@machine:~/brlcad$ git_stats generate
   84 
   85 Note - on Ubuntu, per https://github.com/rails/rails/issues/34822 I had to add the line:
   86 to the git_stats file
   87 
   88 user@machine:~$ echo "gem 'bigdecimal', '1.4.2'" >> /var/lib/gems/2.7.0/gems/git_stats-1.0.17/bin/git_stats
   89 
   90 and install the older version of bigdecimal (per https://stackoverflow.com/a/17026442):
   91 
   92 user@machine:~$ gem install bigdecimal -v 1.4.2
   93 
   94 
   95 ---------------------------------------------------------------------------------
   96 (1) Other large scale git conversions:
   97 https://web.archive.org/web/20130327012743/https://techbase.kde.org/Projects/MovetoGit
   98 https://techbase.kde.org/Projects/MovetoGit
   99 https://blog.runtux.com/posts/2014/04/18/233/
  100 https://blogs.ed.ac.uk/timc/2017/11/24/migrating-from-svn-to-git-while-splitting-repository/
  101 http://esr.ibiblio.org/?p=5634
  102 http://esr.ibiblio.org/?p=6792
  103 http://esr.ibiblio.org/?p=8607
  104 https://gitlab.com/ideasman42/blender-git-migration/