apache

Introduction to Git and GitGUB

Posted on Updated on

On 3/6/19 at 10:30am, I attended the North Carolina Computer Instructor Association Conference Session Introduction to Git and GitHUB at East Carolina University’s SCITech Building in Greenville, NC. This was presented by Michael Schore of Wake Technical Community College.

 

Introduction to Git and GitGUB

  • Without VCS (a version control system), there are problems when you overwrite a file.
  • Why is it good, why use it and what is it?
  • Who should use it?

 

What is a version control system

  • It Tracks changes to files, especially text files
  • Source code for every piece of software or code library is written or has been written in some form of text
  • VCS is also called source code management (SCM)

A version control system is really just a way to take care of added text and then to catalog and understand what text was added, when, and by whom.

History of GIT

Version Control Systems really got their start as coding back in 1972 – SCCS (AT&T). Any participants in the class working then? A few. At the time, attendants were using fortran or punch cards.

1982 RCS much higher performance.

1986 –cvs concurrent use was an issue though

2000 – apache tracked as a subdirectory

2005 – linus torval. Replaced proprietary bitkeeper SCM

 

 

What is a version control system (VCS) Good For?

Think about the tracking required for software or web environment. How many files might be in a basic bootstrap environment? 10? 30?

Initializer.com will assist you in making a basic website with GRID, BOOTSTRAP, etc. Choose one, and it will spit out the basics needed to begin that type of website. Easy, but if you don’t know how to code this, not helpful. Many students may feel initially that using a system like this is smart, helpful, and saves them time, but unfortunately if they do not understand the coding it takes to see, use, change, and adjust this material, they don’t really know how to upkeep the websites they’ve started. In the end, they feel disheartened, upset, and as if they’ve wasted valuable time. Many will choose to have failed rather than put in the time end effort to learn what they have missed.

Without version control in the classroom, students do not always have the steps that many employers would like to have from new employees. Students with an understanding of version control software can quickly and easily move into a software or coding environment, while those without the experience may find themselves having to learn on the job.

Students have excuses, but an online version control system bypasses many of these. If the dog ate their flash drive, the computer fell from the table, etc., anecdotal evidence notwithstanding, having versions of materials available online allow them to go anywhere. They can go to the school lab and work on their materials. They can go directly to the classroom and begin working on it without pause.

 

 

Are Our Students Prepared? Are We Preparing Them?

Modern workflow options require us to ask: Are we really preparing students for jobs in the workplace? If we are teaching students to work on local machines, is this really the industry standard anymore? This opens us up to problems like those noted above. Transportation issues, mechanical and electronic failure, home wi-fi or general connection issues, windows and software updates, etc., can all be blamed without a cloud-based server or version control system. If the students cannot produce the class files at class time, its a real problem

Using GIT and GITHUB is something which can be used to assist students in job availability and preparedness. Employers in coding or web design & development can learn a great deal from a GitHUB. They can see how many updates the students have made, how many active files students are using, how many adjustments they’ve made to existing pieces and how timely the responses are to requests. It allows them to see the technical writing and explanations shown, and many other pieces of material. Imagine the increase in employability this could bring to the table.

Its not all a bed of roses though. An issue with this can be some learned helplessness on the part of our younger, or online students. We need to generate students who break out of their shells and learn to solve problems for themselves. If students don’t feel they have been given a number-by-number, step-by-step approach, many will check out and simply say that they cannot fulfill the project. We need to teach them to rely on themselves and prepare themselves to solve real-world solutions.

Watch this learned helplessness video at: youtube https://www.youtube.com/watch?v=TU7RBqTndJ8

 

What is GIT

Starting in the fall this will be taught in the classrooms at Wake Technical Community College. Git is distributed version control available via the internet or any online connection.

  • No communication requirement with a central server
    • Faster
    • No single point of failure
  • Encourages programmer involvement and “forking” of projects
    • Developers can work independently
    • Can submit change sets for inclusion or rejection

This allows us (both workers such as students and observers such as faculty, bosses, and the general public) to see who checked out individual files, how many lines of code were removed, as well as how many lines of code were added into the environment. It adds accountability into the online group project environment, because there is no way to mask the amount of work done, and code from one update can be checked against code from earlier updates (avoiding duplication and/or copying) as well as against later versions (avoiding duplication and reprinting materials, or having useless code removed later by others..

Who Should Use Git?

  • Anyone needing to track edits in text files
  • Anyone working with appropriate files in a collaborative setting
  • Anyone not afraid to use command-line tools
  • Types of files being worked on
    • Web files (html, css, JS…)
    • Web Programming (PHP, Python, Ruby,Perl, ASP…)
    • Programming (JAVA, C, C++, C#, Objective C…)
    • Offshoots of web languages (like coffeeScript, ActionScript…)
  • Can track other types of files, but not as useful- think images, sound files, etc.

Installing GIT

Nothing difficult about installation. It runs anywhere.

Bash, Apple and unix flavors come with Bash. Windows version installation is an option (GitBash). Having the right-click option to open GitBash from any windows explorer location is a great thing.

Configuring GIT

Systems have all been going to GUI over the years.  Students are afraid of command line. This really allows us to go back to basics and add in another level of professionalism and base-level working knowledge into our classes earlier. Configuring Git is as easy as using the .gitconfig file in the configuration folder.

  • Local Git config file… request slides

Editing GIT

Visual studio code can be used as the visual editor for github. You can also use color output of git.

Repositories

What is a repository? How do you create one? A repository is a place to save and store files. In a VCS, you’re trying to have a backup in case something stupid happens. If you have set up GITHUB and a repository, you can give it some information and choose a day and time to commit to those changes.

How safe is my data? How easily is it destroyed?

At its most basic, its just a file location, created on your development system.

Local repository can be set up, where your development is taking place so you can monitor and record its history.

Remote repository can also be set up, a place where your files can be saved as above, but offsite.

 

Creating A Repository

There is no free lunch. Once git is installed on your computer, its pretty simple to do. Looking at a typical website:

  • Using Git, initialize the project
  • Looking at the directory, we now see a .git file added and a (master) line added.

  

 

At this point in the lecture, we did some hands-on work with GIT to use the materials firsthand. It was a little technical, so I have included the slides as I was not able to type during this time.


  

Best Practices

  • Commit chmessage in example was very simple
  • Commit messages should be a descriptive message about the changes
    • Start with simple single line – 40 to  50 characters
    • Add more lines as needed but less than 70 characters
    • Keep messages in the present tense, not past tense
    • Bullet points using asterisks
    • Add bug number and tracking numbers in the material to be ready for business standards

 

 

Understanding GIT Architecture

Repository >> working >> git add file.html ?? staging >> git commit file.html >> repository

Again, this example was pretty hands-on, so I didn’t have much time for notes and notation.

 

 

GITHUB Training

Find some introductory GIT training and walk though it a few times. Teacher training  to master GIT and Git GUB training via https://education.github.com

Push the workflow ideas on the students. A student who understands GIT can easily understand and pickup the other repository functions. Whatever system suits the company Is the one they’ll use. Think it might be a passing phase? Microsoft bought GITHUB for 7.5 Billion last year.

Where will this go? We’ve recently added in educational contracts with GITHUB and Wake Tech. This allows us a bit of flexibility but can be difficult as it requires schools to work alongside an entity like Microsoft which is itself incredibly large.

 

GITHUB Campus Advisor program

  • As a Github Campus Advisor, you’re not only a master, but a champion of real-world tools at the School.
    • Unlock benefits provided by Github, including a free Github package to meet the needs of your school?
    • Event support, workshop kits and fresh swag delivery every semester
    • Early access to new education features and materials from GitHub education
    • Special invitations to github education events
    • Github camps advisors-only gear and special swag

  

Advertisements

How To Open Source An Internal Project

Posted on Updated on

On 10/22/18 at 9:45pm, I attended the All Things Open Conference Session How To Open Source An Internal Project at the Raleigh Convention Center in Raleigh, NC presented by Vicky Brasseur, Open Source Strategist and Author of Forge Your Future With Open Source.

How To Open Source An Internal Project

This session opened with VM Brasseur (she went by Vicky), introducing herself. She was an open source policy & strategy freelancer, as well as an author & community moderator for opensource.com. She was Vice President of the Open Source Initiative, and I’m the author of this, the first and only book all about how to contribute to open source, available RIGHT NOW beta at the URL above.

That’s just the long way of her saying, “I do this stuff for a living: helping companies understand, use, release, and contribute to FOSS in a way that’s effective both for the bottom line and for the community”. She provided her contact information in the slide, and we were encouraged to use it.

archive.org/details/ato2018-internalproject is where these slides could be found after the event, or currently if you are legally blind or would like your own copy to look at. We were also encouraged to tween during this talk.

So, your company is going to release an internal project as open source. Are you ready for your new responsibilities? You could just throw the code up on a forge like GitHub or GitLab, but it’s unlikely to receive attention or provide much benefit to the company.
Open sourcing an internal project requires a lot of thought and work. Releasing a project as open source requires changes to the development, build, and release workflow. This is not about the code per se; it’s the processes and infrastructure that surround the code that make the project successful.
Topics we’ll cover today include:
  • Identifying company goals for the project
  • Prerelease due diligence (licenses and code hygiene)
  • Community expectations and maintenance
  • Processes that need to happen in the open
  • Communication (internal and external)

This session continued with a question about her book, Forge Your Future With Open Source, and a question about whether or not anyone was reading the book. A person mentioned they had learned about it on the SLACK board, and she inquired about his username. When she knew it, she immediately asked if she could give him a hug. He moved quickly to get it.

“If you get a chance to hug a librarian, you always hug a librarian”. — VM Brasseur

She mentioned that we could quote her on that. It was also mentioned that several NC State Librarians were present at the event, and she should take the time to meet them if she could.

The speaker paused to provide an important key suggestion for other speakers:

Have your first slide include a set of items to be completed prior to the beginning of the presentation, such as:

  • set your timer
  • turn off cellphone
  • remind the audience that your slides are currently available so that they do not have to take photos
  • etc.

Setup some expectations:

If you have already set up the project, a bad release can potentially harm the project. IF you’re looking for an online resource, don’t grab an enterprise-level solution. Don’t damage the potential success of the project by doing a bad job of releasing it because you’re trying to follow some “this is how Big Enterprise does it” sort of guide and thinking that’s all there is to it.

This talk is not a one-stop-solution. There is no silver bullet, so don’t look for one. If someone tells you there is one, be very suspicious. You have a special case. Everyone does. Every company and every project release will be different.

Companies don’t know they should be looking at things before they start, they only know they should have after they are done and trying to monkey patch things after the face.

This talk WILL introduce important concepts that, in my experience helping companies do this sort of thing, I’ve found are most often overlooked or handled poorly.

She’ll be giving us a very high level summary of the steps required. There’s no way to do more than introduce the topics due to the time constraints, but we were encouraged to contact her for a consultation. It’s hard work to release software correctly, and it’s hard work to build and maintain a community around it, but it can be very worthwhile

What even is open source

Lets get on the same page. Brasseur finding that, more and more often, it’s important to clarify this term up front. Because, it turns out, over the past decade of really impressive growth of free and open source software projects and use, folks have lost track of the answer to this very important question. There is a definition:

These definitions are over 30yrs old. Any software described as open source but failing one of these items, is NOT open source by definition. These rights listed above are guaranteed.

Specifically, many people don’t realize that there’s a definition of what it means to be “Open Source”. It’s called the Open Source Definition, it’s maintained by the Open Source Initiative, and it’s accepted around the world as the single canonical definition of open source. Built upon the Four Freedoms and the Debian Free Software Guidelines, the OSD details what is required of any software that calls itself “open source.” Software that does not provide for every one of these 10 items is, literally by definition, not Open Source.

Why should it matter to you

Let’s say you’re building a product at work. You find this software library that does exactly what you need to help your product function. It says it’s “open source,” and you can see the source code right there, so you use it. Then you learn that the maintainer of the library has a different meaning for “open source” than you.

To them, “Open Source” means that you can see the source code, and you can maybe even use the source code, but if you start to make money because of the library then you have to give them all of YOUR source code. Suddenly, you either have to completely rearchitect your product or you need to hand this maintainer your source code, because they were working under a definition of “open source” than you.

Unless we understand and work under the same definition of “Open Source” a great deal of issues can arise.

With a single, accepted definition, you sidestep this problem completely. Everyone’s using the same definition, so anything that says it’s
“open source” should match that definition. However, you still would have the problem of inspecting a project to determine whether it matches that single, accepted definition.

Do you really want to inspect and analyse every single project you use to ensure that it matches the definition? No, of course you don’t. That would take for-EV-er, which means you’d probably never do it, which means you could end up at a BIG risk of using a project that might not meet the definition and require you do do things you don’t expect. But, it’s OK. You don’t have to inspect and analyse all projects. Instead…

The Open Source Initiative does that for you. Or, more specifically, it does it by reviewing licenses under which the software is released. OSI accepts request to review licenses. They look at the license and definition and ensure they are in full agreement. IF agreed, all is good. If failing, you are still allowed to use it, but not all of your freedoms are assured.

To help ensure the freedoms and benefits of the Open Source Definition, the Open Source Initiative reviews software licenses and compares them against the Open Source Definition. Those licenses that obey definition are “OSI-approved.” Because the approved licenses ensure adherence to the Definition, only those projects that use an approved license are guaranteed to be open source. You don’t have to inspect or analyze at all. Just check the license, make sure it’s OSI-approved, and know that it matches the same definition of “open source” that you use.

As you’re looking to release your project, all you have to do is pick a license from this short list, apply it properly to your project (clearly there was not enough time at this point for determining what “properly” means), and you’re off to the races. No need to register the project, no need to get a lawyer involved to draft a license, tons of money saved on analysis and legal fees, plus the peace of mind of knowing that everyone means the same thing when they say “open source.”

Now that we have definitions out of the way, let’s get started with one of the most important but also most ignored steps in releasing an internal project as open source.

Why your company is doing this at all: This is literally the most important first step. If you’re doing this for altruistic purposes, If you love it: great. If you want to gain something: awesome.

what are your benefits and goals? you must internally agree on benefits and goals. If the question brings 5 answers, you have some problems. Your company has and will invest a lot in this thing you’re looking to release If the company receives no benefit from releasing it… And if you can’t all agree on what that benefit is… You’re going to have a lot of problems down the road.

Your answer to this question must be generated to get the proper focus which will guide you through the project. Don’t skip over this step, be honest and realistic.

The moment you give the software, you have multiple stakeholders. The community has to gain a benefit from using the material… Else you lose their trust, their support, and their contributions. Which doesn’t mean your company gains nothing out of it… It just means you have to collaborate in good faith rather than be a greedy pig.

if you don’t have a goal:

  • You won’t know what you want to get out of creating this open source project
  • You will never know if you’re on track or need to change tactics
  • You will not know if you’ve achieved success
  • You cannot define meaningful metrics.
  • You cannot show metrics and results without a goal, its just vanity metrics. IF

Its important to note that in most cases, you’ll be doing this as part of a job or business. If you can’t show any sort of results through your efforts, then your open source effort becomes the lowest hanging fruit when budget cuts roll around. FIGURE THIS OUT UP FRONT

Let’s assume you have goals figured out. What are your next steps? if you cannot show a success to your company, expect to get cut funding and/or get fired

Clean your project. These are things that can get your company into a lot of trouble, so review all code, comments, documentation Are you going to release your GitHub commit history? You better clean that, too.

Badmouthing others will get a nastigram or a lawsuit. Some of us like to swear a lot. Many people, however, aren’t cool with that. Profanity, rudeness and bias will not make others feel welcome— this will hamper the community.

IF you’re going to release, commit to history. You will find most bombs in the documentation and history. Clean it dilligently.

When the project leaves the door and is distributed, that is when licenses get kicked around. The licenses on which you rely must be in compliance. Don’t leave the review to the dev team. Get your IP counsel involved. Don’t play fast and loose with license conditions. Get your IP laywer in the room so that they have a say in everything.

“Distribution” is the trigger for most FOSS licenses. Releasing a project is distribution. Review all of the projects on which your company’s project relies Make sure you’re in compliance with the terms of the licenses of those projects

Clearly Defined is a relatively new but very actively developed and supported project for gathering the information you need for this due diligence. It’s an ever-growing community-driven resource for curated license, copyright, and project source code location information for free and open source software packages It can be a very good way to bootstrap your due diligence process You can learn more about it and contribute at this website. Now that you’ve done your due diligence, now you’re ready to release the project, right? Wrong. There’s still plenty you have to do before the project is released.

You cannot just slam your project onto GitHub and walk away.

Consult with your legal counsel. NOTA BENE! DO NOT IGNORE THE MAINTENANCE OVERHEAD FOR THESE! Figure out this process BEFORE you release the project.

Do you need a cla/dco?

Answer: It depends.

Get your lawyer involved. They will always say “yes!”, because they are risk averse. Walk them through it and talk it up, but don’t underestimate the reasons behind your choices. You have to collect, administer, and commit to them. You have to verify and followup with each item. Most importantly, they are not free.

Other things to think about

There are a lot of other moving parts you need to consider and put in place before releasing the project.

Bug reports. Are there things you want or don’t want to see? Is it essential to get a browser version and name for each item? Start simple to get barebones information which you need to solve the problems. Styleguides might not be an issue, until you see tabs instead of spaces. Set the expectations so that everyone has as good of an experience as possible. An internal Jenkins might be best set to move to an External Travis. You cannot keep everything internal because then… no one can see them

Please provide a code of conduct to start. Just do it. You will get some people who will not work if there is a code of conduct and some who will not work if it does not have one clearly assigned. Get the team trained on how to conduct code of conduct issues.

This is table stakes now, folks. Don’t forget: it’s not enough to have a CoC document. You also have to learn how to enforce it. There are specialists who can help you with this and I strongly recommend you contract with them for training.

These are worderful. Be as detailed as possible to make this work. This should be more of a table of contents to point to the proper pages. You don’t need a ten page annotated document.

TLDR; no one will read if this is too bulky. Make it short and easy to digest.

If you don’t have one, people will invent their own method of contribution and you won’t like it. If you want folks to contribute, you gotta tell them how. This file is how you do it. Be as detailed as necessary. Include pointers to other docs, such as:

  • Setting up dev environment
  • How to open a bug report
  • How to get a patch landed
  • Styleguides
  • Roadmap
  • etc.

If you don’t have one of these, people will just invent their own contribution methods and you probably won’t like that. Head off people making you angry by clearly defining your expectations and the community will do their best to meet your expectations.

This should really be the last thing you do. NOT THE FIRST. If you rely upon copyleft software, you’ll have to have a copyleft license. if you don’t like that, you’ll have to re-architect the entire software package at the end. Don’t use your personal preferences, use the model your end user wishes. Do it right.

Everyone always jumps to this step first, but it doesn’t actually have to be done until just before you release the project. License selection may be influenced by the license conditions of the projects on which yours relies. Start at GPLv3. If that won’t work for business reasons (do at least try it, OK?) Fall back to Apache, then BSD-3, then MIT. It’s a spectrum.

LIcense or copying in the repository is real. add copyright notice to each file. add license notice to each file. If you’re purchased, don’t make the users have a burden of proof that the early item was available. Its a perl script people, automate it!

Take guidance from the GPL instructions. They are usually seen as the most thorough. Few other licenses provide instructions. Thanks, FSF! A PITA? Dude, this stuff can be automated

You probably need to market your project, but that hasn’t really been discussed here. there is another session later (Diedre) who may cover that.

Remember that I mentioned earlier that releasing the project is only the start. Once it’s out there, your company can’t maximize its benefits without the help of a community.

You can’t gain any of those benefits without building a community. You can’t build a community without building trust .So how do you do that? How do you build trust?

Without trust, you cannot get benefits. How to build trust and get a community? You have to work in the open—all project and management work in the open.

All open source bits must be in the public. All development work happens in the open where everyone can see & participate in it. Features aren’t developed in quiet in-house and then popped on the community.They will want to contribute. All build processes should operate in the open and publicly. They won’t know what it is and how good it is.

The project accepts contributions of all sort from the community Community collaboration and influence in the roadmap Community should feel like a primary stakeholder in the project, not simply a low cost workforce Community participates in all elements of project governance

Let others contribute. Collaborate, let them influence the roadmap. Keep the external open source moving. Its tough, but its possible. they are primary stakeholders, not a cheap labor force.

All of this will take time Building a community takes time. Building trust takes time. Don’t be in a rush. If your company works consistently in the open and in the best interests of the community, it will see the benefits and it will meet its goals. It’s just not going to happen overnight.

Q & A

Can you stop people from using your open source software if they are using it for illegal means?

No. unfortunately, once its open, its open. YOu will not be held liable for the action though. Even she cannot stop users from useing the material. She’d love to stop Nazis, homophobes, transphobes, etc. from using it, but she cannot. Now she might not meld their updates and force them to do it themselves, but she will not be able to hold back any aspects of what is released.

Should the licenses really, really be in every file? Even CNF files?

YES. the copyright and license file should be in each file. Every reasonable file will have comment sections. Just place it in every single file at the top. As you pluck a single file out, it looses the association with the copyright and license information from the original folder

should the ENTIRE material be in each file

NO. its in the book, but essentially copyright, year, company, copyright found in c: (github) location