I'm editing one of my open-source projects on GitHub and I want to replace link (pointing to a demo) in README.md.
Do I have to update library version every time I introduce some minor changes to the README file or documentation (without any actual code changes)?
What is the community accepted practice?
If it's important, I'm using Bower to distribute my package and SemVer as a versioning system.
The README file is part of your codebase. It should describe the current (= in current commit) state of the code. A developer might read it outside GitHub's environment, e.g. from the node_modules directory on their hard drive, expecting it is up to date.
Therefore I would recommend to release a new version when the README changes.
It will usually result in just a patch number increase. But remember that when marking something as deprecated one must release a new minor version (paragraph 7 in SemVer v2.0.0).
If you plan to do really a lot of changes there are two ways to avoid releasing too often:
Make changes in a branch. Merge to master here and there, release a new patch version.
Move the documentation (or a part of it) somewhere else. GitHub Wiki or a simple webpage, e.g. using GitHub Pages, could come in handy.
You could include, as library version, the content of of git describe --all --long, as described in How can I get the Git build number and embed it in a file? (using git describe).
That way, you get the latest tag, plus the number of (small) commits you did since that tag.
That means:
you don't have to put a new tag if you don't want to
but you still keep an exact reference the the version of your repo which was used for delivering your app.
Related
This is a perl-module specific question:
I already have my history and version tags in git so it would be nice to sync ./Changes with git log just before publishing the module update.
Specifically I am looking for something that generates the Changes file in the format that perl module Changes files are supposed to be in for a CPAN summary:
<version> <date>
Change 5
Change 6
<version> <date>
Change 3
Change 4
<version> <date>
Change 1
Change 2
The way I write my commits, the git log --online entry is correctly formatted for a Changes file, no unnecessary noise. At least for the moment since I'm the only author this is a consistent policy.
How would you make git --online create a version file based on tags and iteratively get the --online entries for each tag?
I take a bit of a different approach an automatically Δ£enerate a Release file that is signed by my gpg key as part of the release on cpan.
if you use Dist::Zilla as part of your release process it could be added into dist.ini. It is available at https://metacpan.org/pod/Dist::Zilla::Plugin::SignReleaseNotes
I use it to publish a release note on github.com for my modules that has the checksum of the cpan release file and the git commits since the last release all in a signed message. See https://github.com/perl-net-saml2/perl-Net-SAML2/releases for an example.
I still maintain a separate Changes file. If this helps great if not the code in there will show you how to get the online commits between the latest tag an the previous.
There are plenty of programs that will generate a changelog file from a Git commit history (just search on Github for things like "gitlog2changelog"). I've even used them in the past.
But it's a terrible idea.
Your documentation will already contain a link to your Git repo. So anyone who wants it will be able to get access to your commit history. But, depending on your commit and merge strategies, that's likely to contain far too much information to be useful to most people.
A changelog (in my opinion, at least) should be a higher-level summary of the changes in your project. You should be reading the commit history and using that to create a useful summary of the changes.
See Keep a ChangeLog for more details about what a ChangeLog should look like.
I created an Angular project using angular-cli and pushed it to GitHub. I then created a new branch and updated packages, installed standard-version and ran npm run release -- --first-release as instructed. I then pushed the whole into a new branch on GitHub, created a pull request, squashed and merged onto master, pulled back into local master, and ran standard-version again finally followed by git push --follow-tags origin master. Here's the state on GitHub:
All notes that I wrote in the pull request body are not visible in the changelog file, and they are obviously not in the chore(release) generated by standard-version. Why?
They are also not written within the Releases tabs at all, even though I can see the released tags there.
Should I have made the version 1.0.0 in packages.json before starting in order to adhere to semantic versioning?
What am I doing wrong?
You're not doing anything wrong. chore doesn't show up in CHANGELOG.md (see: https://github.com/conventional-changelog/standard-version/issues/135)
To have release notes uploaded, you will to use something like https://github.com/conventional-changelog/conventional-github-releaser
It's up to you where to start. Generally, when labeled 0.x, the project is still unstable and will go through vast API changes. When the project becomes stable, bump the major to 1.x and adhere to semver.
We have been using mercurial for over two years for our flex/as3 projects. Over the time, we came up with several projects and a common library which is used/referenced by the projects. In order to maintain the versioning properly, each time a new version is tagged on a project repo, the same tag is applied to library repo, as well.
This is done manually. I am not sure whether what we do which was described above is the correct way but I wonder if there is any (other) way to relate project repos to library repo, so that whenever i want to pull a specific version of a project, i will know exactly what version of library should be pulled.
Any thoughts? Thanks.
Have you ever tried subrepo? By using subrepo, hg will maintain the whole project with the subrepo.
For example, if you have HG_DIR/lib as the library and it is a subrepo to the HG_DIR, then when committing in HG_DIR, hg will remember which rev of HG_DIR/lib you are using with, which means a commit in HG_DIR links with a commit in HG_DIR/lib.
hg subrepo supports multiple VCS subrepos, too.
Update:
As #alexis suggested, use recommendation from the official documentation, lib should be treated as siblings of project:
HG_DIR/
lib1/
lib2/
project/
I'd like to manage the GitHub wiki for my project at the same time as I'm developing the code. For example:
Branches
master (stable versions)
develop (development of next version)
Others... (Possible other dev / feature branches)
Ideally, I'd like the wiki to be contained in a subfolder (e.g. /wiki) of the project. Then when I'm making changes to the code I can also update the wiki as the same time (code + documentation change). It'd also mean that all my development code and documentation would be self-contained in the "develop" branch until I merge with the "master" branch. Hopefully, even if via a manual process, the GitHub wiki would then be updated after the merge with master to reflect the changes.
I've taken a look at Git's submodule feature, but from what I understand that usually points at a single revision. I'd like to somehow follow my code development so branching and merging would work as normal.
As explained in "True nature of submodules", you can make modifications and updates within a submodule, as long as you commit also the parent repo in order to record the new state of your "wiki" sub-repo.
If you intend to use Gollum to display and work on your GitHub wiki while it's on your local machine (you probably should), then you will have a trouble if you use submodules.
Gollum wants to do local commits to your local Git repository (but not pushes), but in a submodule .git is actually a file containing the local repository, not a true Git repository. This causes Gollum to break.
Submodules also have the problems that the versions aren't coupled to the parent repository, and they aren't completely de-coupled. It a nuisance to have the source code repository to want to push the new wiki version number (but not the wiki contents) every time you make a documentation change.
The solution I use is simply to clone the wiki repository into a directory inside the main project directory and add it to .gitignore. By using a consistent name for the directory across projects (e.g. github-wiki), the chance is minimized that the wiki won't be in .gitignore and gets accidentally uploaded into the main repository.
For consistency, his approach also works well for GitHub pages, although it's unnecessary as they don't experience the problem with Gollum.
I've just started using subversion, and have read the official documentation (svn book), cheat sheet and a couple of guides. I know how to install subversion (in linux), create a repository (svnadmin create), and import my Eclipse project into the repository (SVN import), view the repository files (using svn list).
But I am unable to understand some of the other terminologies. For example, after importing my Eclipse project into the newly created repository I have made changes to my Eclipse project (more than 1 file). Now, how should I update the repository with this added files/changes made to my Eclipse project?
The svn update command brings the changes from the repository into your working copy - which is the opposite of what I want i.e. bring the changes I made in my Eclipse project into the previously imported project in repository. If I am correct, you update the repository more often (as you keep extending your project implementation) than your current project (with update).
Also, I do not understand when would you use svn merge. The svn book states it applies the differences between 2 sources to a working copy. Is there a scenario which would explain this?
Finally, can I have more than 1 project checked into the repository? Or is it better to create a new repository for each project?
The term you are looking for is "commit".
Subversion does not exclusively lock a file for editing (though there is a command to do this if you really, really want to). So it is possible that you will need to merge two different users' sets of edits on a file, or even edits from two different working copies in two different locations on your machine.
Multiple projects is fine. Best approach IMHO is repository/project/trunk etc rather than repository/trunk/project.
Three things about SVN you should know:
Trunk - The main version of your code
Tags - 'Tagged' Versions of your code (i.e. v1.2.5-release)
Branches - Forks of the code for divergent development paths. We typically fork new branches to work on different versions, so if the current version is 1.2.4, you'd branch for 1.3's development. So if emergency changes to 1.2 need to be made (i.e. 1.2.5) you can work on it without worrying about what you broke by refactoring / feature adding in your 1.3 branch. The merge operation is designed so you can merge 1.3's branch back into trunk when you're ready to release 1.3, or a similar operation. You can also merge individual files (if two or more developers edited the same file at the same time and now you need to 'merge' the changes into the same file.
Each project in your repository should have 3 folders in it:
/trunk
/branches
/tags
These house the three points above. You don't have to have these folders, but you should. Other more mature VCS like Mericual/Git have the concepts of tags and branches baked into the system. In SVN these are more of a convention/reccomendation.
Terminology
Working Copy - The copy on your hard-drive, that contains all your edits, etc...
Add - Registers a file for tracking in version control
Update - Updates the working copy with changes from the server repository
Commit - Updates the server repository with changes from the working copy
Switch - Replaces the working copy with another folder within the server repository
Diff - Does a differential analysis of two files / versions of a file to see the changes between them.
Merge - Attempts to apply the changes from one or more files into another, highlighting conflicts.
Patch - A set of differences that can be used to update a file.
You commit changes to the repository
Merge is useful when you need to maintain two branches of a repository. For examples v1.x with most recent security fixes and the alpha version 2. That allows you to make the fixes in the 1.x code, whith the resulting binary for existing customers, and you can merge the changes into version 2 so fixing the bugs that weren't already caught.
I suggest you look around for 'typical svn workflows'. They will give you the big picture of the 'most common tasks'.
What you want to do is 'commit' the changes made to your files to the repository.
You need to merge in case of a conflict (when 2 or more people are working on a project and commit to the same repo. conflicts might arise).
Check the available articles on SVN kai remember to read about the sample/typical workflows or working scenarios with SVN.
Fully agree with David, but as far as question 3 is concerned, personally, I would distinguish between use cases:
Production: One project per repository. And do get warm with the mentioned tag/trunk/branch concept, it really helps a lot
Testing: I have one single repository where I have put virtually all my experimental codes (approx. 10 languages with x codes per language). Reason is: One experimental code takes me 1-2 minutes, creating a repository on a remote host, using ssh-security sometimes takes longer ;-)
Cheers
EL